feat: support imports map in package.json

Author: privatenumber

README.md

@@ -114,6 +114,22 @@ This automatically bundles all matching source files. For example:
 > [!IMPORTANT]
 > Wildcard patterns must include a file extension (e.g., `.mjs`, `.cjs`)
 
+#### Subpath Imports
+
+_Pkgroll_ supports building entry-points defined in [`package.json#imports` (Node.js subpath imports)](https://nodejs.org/api/packages.html#subpath-imports), including conditional imports:
+
+```json
+{
+    "imports": {
+        "#my-pkg": "./dist/index.js",
+        "#env": {
+            "node": "./dist/env.node.js",
+            "default": "./dist/env.browser.js"
+        }
+    }
+}
+```
+
 ### Output formats
 _Pkgroll_ detects the format for each entry-point based on the file extension or the `package.json` property it's placed in, using the [same lookup logic as Node.js](https://nodejs.org/api/packages.html#determining-module-system).
 
@@ -171,9 +187,6 @@ You can configure aliases using the [import map](https://nodejs.org/api/packages
 
 In Node.js, import mappings must start with `#` to indicate an internal [subpath import](https://nodejs.org/api/packages.html#subpath-imports). However, _Pkgroll_ allows defining aliases **without** the `#` prefix.
 
-> [!NOTE]
-> While Node.js supports conditional imports (e.g., different paths for Node.js vs. browsers), _Pkgroll_ does not.
-
 Example:
 
 ```json5

src/rollup/configs/dts.ts

@@ -3,6 +3,7 @@ import type { TsConfigResult } from 'get-tsconfig';
 import { nodeBuiltins } from '../plugins/node-builtins.js';
 import { resolveJsToTs } from '../plugins/resolve-js-to-ts.js';
 import { resolveTsconfigPaths } from '../plugins/resolve-tsconfig-paths.js';
+import { externalPkgImports } from '../plugins/external-pkg-imports.js';
 import type { Options, Output } from '../types.js';
 
 export const getDtsConfig = async (
@@ -24,6 +25,7 @@ export const getDtsConfig = async (
 		input: {} as Record<string, string>,
 		preserveEntrySignatures: 'strict' as const,
 		plugins: [
+			externalPkgImports(),
 			nodeBuiltins(options),
 			...(
 				tsconfig

src/rollup/configs/pkg.ts

@@ -15,6 +15,7 @@ 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 { externalPkgImports } from '../plugins/external-pkg-imports.js';
 import type { Options, Output } from '../types.js';
 import type { EntryPointValid } from '../../utils/get-build-entry-points/types.js';
 import { cjsAnnotateExports } from '../plugins/cjs-annotate-exports.js';
@@ -56,6 +57,7 @@ export const getPkgConfig = (
 			alias({
 				entries: aliases,
 			}),
+			externalPkgImports(),
 			nodeResolve({
 				extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json'],
 				exportConditions: options.exportCondition,

src/rollup/plugins/external-pkg-imports.ts

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import type { Plugin } from 'rollup';
+import { slash } from '../../utils/normalize-path.js';
+
+/**
+ * Externalize package imports from the current package so Node.js
+ * resolves them at runtime using package.json#imports
+ * https://nodejs.org/api/packages.html#subpath-imports
+ */
+export const externalPkgImports = (): Plugin => {
+	// Resolve to canonical path to handle Windows 8.3 short paths
+	const cwd = fs.realpathSync.native(process.cwd());
+	return {
+		name: 'external-pkg-imports',
+		resolveId(id, importer) {
+			if (id[0] !== '#') {
+				return null;
+			}
+
+			if (importer) {
+				// Get path relative to cwd
+				const relativePath = slash(path.relative(cwd, importer));
+				// Check if importer is from a dependency (has /node_modules/ path segment)
+				const pathSegments = relativePath.split('/');
+				if (pathSegments.includes('node_modules')) {
+					// Let Node-resolver handle imports maps from dependencies
+					return null;
+				}
+			}
+
+			// Import is from current package, externalize it
+			return {
+				id,
+				external: true,
+			};
+		},
+	};
+};

src/rollup/plugins/native-modules.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { Plugin } from 'rollup';
+import { slash } from '../../utils/normalize-path.js';
 
 const PREFIX = '\0natives:';
 
@@ -75,9 +76,9 @@ export const nativeModules = (
 			}
 
 			// Generate the require path relative to the final bundle directory
-			const relativePath = `./${path.relative(distDirectory, destinationPath)}`;
+			const relativePath = `./${slash(path.relative(distDirectory, destinationPath))}`;
 
-			return `export default require("${relativePath.replaceAll('\\', '/')}");`;
+			return `export default require("${relativePath}");`;
 		},
 
 		generateBundle: async () => {

src/utils/get-build-entry-points/expand-exports-wildcards.ts

@@ -48,9 +48,9 @@ export const expandBuildOutputWildcards = async (
 	const expandedResults = await Promise.all(
 		buildOutputs.map(async (output) => {
 			if (
-				// Only process exports wildcards (not main/module/types/bin/cli)
+				// Only process exports/imports wildcards (not main/module/types/bin/cli)
 				typeof output.source === 'string'
-				|| output.source.path[0] !== 'exports'
+				|| (output.source.path[0] !== 'exports' && output.source.path[0] !== 'imports')
 
 				// Skip non-wildcard entries
 				|| !output.outputPath.includes('*')

src/utils/get-build-entry-points/get-pkg-entry-points.ts

@@ -1,66 +1,76 @@
 import type { PackageJson } from 'type-fest';
 import { normalizePath } from '../normalize-path.js';
-import type { PackageType, BuildOutput, ObjectPath } from './types.js';
+import type {
+	PackageType, BuildOutput, ObjectPath, PackageMapType,
+} from './types.js';
 import { getFileType, isPath } from './utils.js';
 
 const getConditions = (
 	fromPath: ObjectPath,
 ) => fromPath.slice(1).filter(part => (typeof part === 'string' && part[0] !== '.')) as string[];
 
-const parseExportsMap = (
-	exportMap: PackageJson['exports'],
+const parsePackageMap = (
+	packageMap: PackageJson['exports'] | PackageJson['imports'],
 	packageType: PackageType,
-	packagePath: ObjectPath = ['exports'],
+	mapType: PackageMapType,
+	packagePath: ObjectPath = [mapType],
 ): BuildOutput[] => {
-	if (!exportMap) {
+	if (!packageMap) {
 		return [];
 	}
 
-	if (typeof exportMap === 'string') {
+	if (typeof packageMap === 'string') {
 		return [{
 			source: {
 				type: 'package.json',
 				path: [...packagePath],
 			},
-			type: 'exportmap',
+			type: mapType,
 			conditions: [],
-			format: getFileType(exportMap) || packageType,
-			outputPath: normalizePath(exportMap),
+			format: getFileType(packageMap) || packageType,
+			outputPath: normalizePath(packageMap),
 		}];
 	}
 
-	if (Array.isArray(exportMap)) {
-		return exportMap.flatMap(
-			(exportPath, index) => {
+	if (Array.isArray(packageMap)) {
+		return packageMap.flatMap(
+			(mapPath, index) => {
 				const from = [...packagePath, index];
 				return (
-					typeof exportPath === 'string'
+					typeof mapPath === 'string'
 						? (
-							isPath(exportPath)
+							isPath(mapPath)
 								? {
 									source: {
 										type: 'package.json',
 										path: [...from],
 									},
-									type: 'exportmap',
+									type: mapType,
 									conditions: getConditions(from),
-									format: getFileType(exportPath) || packageType,
-									outputPath: normalizePath(exportPath),
+									format: getFileType(mapPath) || packageType,
+									outputPath: normalizePath(mapPath),
 								}
 								: []
 						)
-						: parseExportsMap(exportPath, packageType, from)
+						: parsePackageMap(mapPath, packageType, mapType, from)
 				);
 			},
 		);
 	}
 
-	return Object.entries(exportMap).flatMap(([key, value]) => {
+	const isImports = mapType === 'imports' && packagePath.length === 1;
+	return Object.entries(packageMap).flatMap(([key, value]) => {
+		// For imports, only process # imports at the top level
+		// Nested keys are export conditions (node, default, etc.)
+		if (isImports && key[0] !== '#') {
+			return [];
+		}
+
 		const from = [...packagePath, key];
 		if (typeof value === 'string') {
 			const conditions = getConditions(from);
 			const baseEntry = {
-				type: 'exportmap' as const,
+				type: mapType,
 				source: {
 					type: 'package.json' as const,
 					path: from,
@@ -82,7 +92,7 @@ const parseExportsMap = (
 			};
 		}
 
-		return parseExportsMap(value, packageType, from);
+		return parsePackageMap(value, packageType, mapType, from);
 	});
 };
 
@@ -162,10 +172,13 @@ export const getPkgEntryPoints = (
 	}
 
 	if (packageJson.exports) {
-		const exportMap = parseExportsMap(packageJson.exports, packageType);
-		for (const exportEntry of exportMap) {
-			pkgEntryPoints.push(exportEntry);
-		}
+		const exportMap = parsePackageMap(packageJson.exports, packageType, 'exports');
+		pkgEntryPoints.push(...exportMap);
+	}
+
+	if (packageJson.imports) {
+		const importEntries = parsePackageMap(packageJson.imports, packageType, 'imports');
+		pkgEntryPoints.push(...importEntries);
 	}
 
 	return pkgEntryPoints;

src/utils/get-build-entry-points/types.ts

@@ -22,8 +22,10 @@ export type BinaryOutput = Output<SourcePackageJson> & {
 	type: 'binary';
 };
 
-export type ExportMapOutput = Output<SourcePackageJson> & {
-	type: 'exportmap';
+export type PackageMapType = 'exports' | 'imports';
+
+export type PackageMapOutput = Output<SourcePackageJson> & {
+	type: PackageMapType;
 	conditions: string[];
 };
 
@@ -33,7 +35,7 @@ export type LegacyOutput = Output<OutputSource> & {
 	isExecutable?: boolean;
 };
 
-export type BuildOutput = BinaryOutput | ExportMapOutput | LegacyOutput;
+export type BuildOutput = BinaryOutput | PackageMapOutput | LegacyOutput;
 
 export type EntryPointValid<T extends BuildOutput = BuildOutput> = {
 	sourcePath: string;

src/utils/normalize-path.ts

@@ -1,5 +1,8 @@
 import path from 'node:path';
 
+// Convert Windows backslashes to forward slashes
+export const slash = (p: string) => p.replaceAll('\\', '/');
+
 export const normalizePath = (
 	filePath: string,
 	isDirectory?: boolean,

tests/specs/builds/dependencies.ts

@@ -227,7 +227,6 @@ export default testSuite(({ describe }, nodePath: string) => {
 
 		test('imports map - node', async () => {
 			await using fixture = await createFixture(fixtureDependencyImportsMap);
-
 			const pkgrollProcess = await pkgroll(['--export-condition=node'], {
 				cwd: fixture.path,
 				nodePath,