feat: support native .node bundling (#68)

Co-authored-by: Hiroki Osame <hiroki.osame@gmail.com>

Author: roryabraham

README.md

@@ -249,6 +249,40 @@ Sometimes it's useful to use `require()` or `require.resolve()` in ESM. ESM code
 
 When compiling to ESM, _Pkgroll_ detects `require()` usages and shims it with [`createRequire(import.meta.url)`](https://nodejs.org/api/module.html#modulecreaterequirefilename).
 
+### Native modules
+
+_pkgroll_ automatically handles native Node.js addons (`.node` files) when you directly import them:
+
+```js
+// src/index.js
+import nativeAddon from './native.node'
+```
+
+After bundling, the `.node` file will be copied to `dist/natives/` and the import will be automatically rewritten to load from the correct location at runtime.
+
+> [!NOTE]
+> - Native modules are platform and architecture-specific. Make sure to distribute the correct `.node` files for your target platforms.
+> - This only works with direct `.node` imports. If you're using packages that dynamically load native modules via `bindings` or `node-pre-gyp`, you'll need to handle them separately.
+
+#### Handling dependencies with native modules
+
+If you're using packages with native modules (like `chokidar` which depends on `fsevents`):
+
+- **If in `dependencies`/`peerDependencies`**: ✅ Works automatically - these are externalized (not bundled)
+- **If in `devDependencies`**: ⚠️ Will be bundled. If they use `bindings()` or `node-pre-gyp` patterns, move them to `dependencies` instead, or use `optionalDependencies` if they're optional.
+
+Example - if you have `chokidar` in `devDependencies` and get build errors, move it to `dependencies`:
+
+```json
+{
+    "dependencies": {
+        "chokidar": "^3.0.0"
+    }
+}
+```
+
+This externalizes it (users will need to install it), avoiding the need to bundle its native modules.
+
 ### Environment variables
 Pass in compile-time environment variables with the `--env` flag.
 

package.json

@@ -65,11 +65,11 @@
 		"cleye": "^1.3.4",
 		"estree-walker": "^3.0.3",
 		"execa": "9.6.0",
-		"fs-fixture": "^2.8.1",
+		"fs-fixture": "^2.9.0",
 		"get-node": "^15.0.4",
 		"get-tsconfig": "^4.10.1",
 		"kolorist": "^1.8.0",
-		"lintroll": "^1.19.1",
+		"lintroll": "^1.20.1",
 		"manten": "^1.5.0",
 		"outdent": "^0.8.0",
 		"react": "^19.1.1",

pnpm-lock.yaml

@@ -14,6 +14,7 @@ import { resolveJsToTs } from '../plugins/resolve-js-to-ts.js';
 import { resolveTsconfigPaths } from '../plugins/resolve-tsconfig-paths.js';
 import { stripHashbang } from '../plugins/strip-hashbang.js';
 import { esmInjectCreateRequire } from '../plugins/esm-inject-create-require.js';
+import { nativeModules } from '../plugins/native-modules.js';
 import type { Options, Output } from '../types.js';
 import type { EntryPointValid } from '../../utils/get-entry-points/types.js';
 import { cjsAnnotateExports } from '../plugins/cjs-annotate-exports.js';
@@ -23,6 +24,7 @@ export const getPkgConfig = (
 	aliases: AliasMap,
 	entryPoints: EntryPointValid[],
 	tsconfig: TsConfigResult | null,
+	distDirectory: string,
 ) => {
 	const env = Object.fromEntries(
 		options.env.map(({ key, value }) => [`process.env.${key}`, JSON.stringify(value)]),
@@ -71,6 +73,7 @@ export const getPkgConfig = (
 				warnOnError: true,
 			}),
 			esmInjectCreateRequire(),
+			nativeModules(distDirectory),
 			...(
 				options.minify
 					? [esbuildMinify(esbuildConfig)]

src/rollup/configs/pkg.ts

@@ -96,11 +96,14 @@ export const getRollupConfigs = async (
 
 		let config = configs.pkg;
 		if (!config) {
+			// Use the first dist directory for shared assets (chunks, natives)
+			const firstDistDirectory = srcdistPairs[0].dist;
 			config = getPkgConfig(
 				flags,
 				aliases,
 				entryPoints,
 				tsconfig,
+				firstDistDirectory,
 			);
 			config.external = getExternalDependencies(packageJson, aliases);
 			configs.pkg = config;

src/rollup/get-rollup-configs.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { Plugin } from 'rollup';
+
+const PREFIX = '\0natives:';
+
+/**
+ * Handles native Node.js addons (.node files)
+ * - Stage 1 (resolve/load): Identifies .node files and generates runtime code.
+ * - Stage 2 (generateBundle): Copies the identified .node files to the output dir.
+ */
+export const nativeModules = (
+	distDirectory: string,
+): Plugin => {
+	const nativeLibsDirectory = `${distDirectory}/natives`;
+	// Map<original_path, final_destination_path>
+	const modulesToCopy = new Map<string, string>();
+
+	return {
+		name: 'native-modules',
+
+		buildStart: () => {
+			modulesToCopy.clear();
+		},
+
+		async resolveId(source, importer) {
+			if (source.startsWith(PREFIX) || !source.endsWith('.node')) {
+				return null;
+			}
+
+			const resolvedPath = importer
+				? path.resolve(path.dirname(importer), source)
+				: path.resolve(source);
+
+			try {
+				await fs.access(resolvedPath);
+			} catch {
+				this.warn(`Native module not found: ${resolvedPath}`);
+				return null;
+			}
+
+			const basename = path.basename(resolvedPath);
+			let outputName = basename;
+			let counter = 1;
+
+			// Handle name collisions by checking already staged values
+			const stagedBasenames = new Set(
+				Array.from(modulesToCopy.values()).map(p => path.basename(p)),
+			);
+			while (stagedBasenames.has(outputName)) {
+				const extension = path.extname(basename);
+				const name = path.basename(basename, extension);
+				outputName = `${name}_${counter}${extension}`;
+				counter += 1;
+			}
+
+			const destinationPath = path.join(nativeLibsDirectory, outputName);
+			modulesToCopy.set(resolvedPath, destinationPath);
+
+			// Return a virtual module ID containing the original path
+			return PREFIX + resolvedPath;
+		},
+
+		load(id) {
+			if (!id.startsWith(PREFIX)) {
+				return null;
+			}
+
+			const originalPath = id.slice(PREFIX.length);
+			const destinationPath = modulesToCopy.get(originalPath);
+
+			if (!destinationPath) {
+				// Should not happen if resolveId ran correctly
+				return this.error(`Could not find staged native module for: ${originalPath}`);
+			}
+
+			// Generate the require path relative to the final bundle directory
+			const relativePath = `./${path.relative(distDirectory, destinationPath)}`;
+
+			return `export default require("${relativePath.replaceAll('\\', '/')}");`;
+		},
+
+		generateBundle: async () => {
+			if (modulesToCopy.size === 0) {
+				return;
+			}
+
+			// Create the directory once.
+			await fs.mkdir(nativeLibsDirectory, { recursive: true });
+
+			// Copy all staged files in parallel.
+			await Promise.all(
+				Array.from(modulesToCopy.entries()).map(
+					([source, destination]) => fs.copyFile(source, destination),
+				),
+			);
+		},
+	};
+};

src/rollup/plugins/native-modules.ts

@@ -8,6 +8,7 @@ export default testSuite(({ describe }, nodePath: string) => {
 		runTestSuite(import('./output-types.js'), nodePath);
 		runTestSuite(import('./env.js'), nodePath);
 		runTestSuite(import('./define.js'), nodePath);
+		runTestSuite(import('./native-modules.js'), nodePath);
 		runTestSuite(import('./target.js'), nodePath);
 		runTestSuite(import('./minification.js'), nodePath);
 		runTestSuite(import('./package-exports.js'), nodePath);

tests/specs/builds/index.ts

@@ -0,0 +1,122 @@
+import { testSuite, expect } from 'manten';
+import { createFixture } from 'fs-fixture';
+import { pkgroll } from '../../utils.js';
+import { createPackageJson } from '../../fixtures.js';
+
+export default testSuite(({ describe }, nodePath: string) => {
+	describe('native modules', ({ test }) => {
+		test('ESM: copies .node files to natives directory', async () => {
+			await using fixture = await createFixture({
+				'package.json': createPackageJson({
+					type: 'module',
+					main: './dist/index.mjs',
+				}),
+				'src/index.js': `
+					import native from './native.node';
+					console.log(native);
+				`,
+				'src/native.node': Buffer.from('dummy native module'),
+			});
+
+			const pkgrollProcess = await pkgroll([], {
+				cwd: fixture.path,
+				nodePath,
+			});
+
+			expect(pkgrollProcess.exitCode).toBe(0);
+			expect(pkgrollProcess.stderr).toBe('');
+
+			// Check that natives directory was created
+			expect(await fixture.exists('dist/natives')).toBe(true);
+
+			// Check that .node file was copied
+			const files = await fixture.readdir('dist/natives');
+			expect(files.some(file => file.endsWith('.node'))).toBe(true);
+
+			// Check that import was rewritten and uses createRequire for ESM
+			const content = await fixture.readFile('dist/index.mjs', 'utf8');
+			expect(content).toMatch('./natives');
+			expect(content).toMatch('createRequire');
+		});
+
+		test('CJS: copies .node files to natives directory', async () => {
+			await using fixture = await createFixture({
+				'package.json': createPackageJson({
+					type: 'commonjs',
+					main: './dist/index.cjs',
+				}),
+				'src/index.js': `
+					import native from './native.node';
+					console.log(native);
+				`,
+				'src/native.node': Buffer.from('dummy native module'),
+			});
+
+			const pkgrollProcess = await pkgroll([], {
+				cwd: fixture.path,
+				nodePath,
+			});
+
+			expect(pkgrollProcess.exitCode).toBe(0);
+			expect(pkgrollProcess.stderr).toBe('');
+
+			// Check that natives directory was created
+			expect(await fixture.exists('dist/natives')).toBe(true);
+
+			// Check that .node file was copied
+			const files = await fixture.readdir('dist/natives');
+			expect(files.some(file => file.endsWith('.node'))).toBe(true);
+
+			// Check that import was transformed to require for CJS
+			const content = await fixture.readFile('dist/index.cjs', 'utf8');
+			expect(content).toMatch('./natives');
+			expect(content).toMatch('require');
+			// Should NOT have createRequire in CJS output
+			expect(content).not.toMatch('createRequire');
+		});
+
+		test('handles multiple src:dist pairs', async () => {
+			await using fixture = await createFixture({
+				'package.json': createPackageJson({
+					exports: {
+						'./a': './dist-a/index.js',
+						'./b': './dist-b/index.js',
+					},
+				}),
+				'src-a/index.js': `
+					import native from './native-a.node';
+					console.log(native);
+				`,
+				'src-a/native-a.node': Buffer.from('native module a'),
+				'src-b/index.js': `
+					import native from './native-b.node';
+					console.log(native);
+				`,
+				'src-b/native-b.node': Buffer.from('native module b'),
+			});
+
+			const pkgrollProcess = await pkgroll([
+				'--srcdist',
+				'src-a:dist-a',
+				'--srcdist',
+				'src-b:dist-b',
+			], {
+				cwd: fixture.path,
+				nodePath,
+			});
+
+			expect(pkgrollProcess.exitCode).toBe(0);
+			expect(pkgrollProcess.stderr).toBe('');
+
+			// Should create natives in the first dist directory (like shared chunks)
+			expect(await fixture.exists('dist-a/natives')).toBe(true);
+			expect(await fixture.exists('dist-b/natives')).toBe(false);
+
+			// Check both .node files were copied to first dist
+			const files = await fixture.readdir('dist-a/natives');
+			expect(files.length).toBeGreaterThanOrEqual(2);
+			expect(files.some(file => file.includes('native-a'))).toBe(true);
+			expect(files.some(file => file.includes('native-b'))).toBe(true);
+		});
+	});
+});