pkgbld 2.0.0 → 2.1.0

package/README.md

@@ -43,6 +43,30 @@ For TypeScript or TSX sources, also install
 
 `pkgbld` expects the name field to be filled in the package.json file. `exports` field defines what entries/outputs should be built for this package.
 
+### Private package imports
+
+When `package.json` has an `imports` map, `pkgbld` builds its local JavaScript targets alongside the public `exports` entries. For example:
+
+```json
+{
+  "name": "example",
+  "type": "module",
+  "imports": {
+    "#utils": "./dist/utils.mjs",
+    "#env": {
+      "node": "./dist/env.node.mjs",
+      "default": "./dist/env.browser.mjs"
+    }
+  }
+}
+```
+
+With the default directories, provide `src/utils.js`, `src/env.node.js`, and `src/env.browser.js` (or supported TypeScript sources with a transform plugin). Both `#env` branches are built at the declared paths. An import of `#utils` or `#env` from this package stays as a `#` specifier in the output, so the runtime selects the matching branch. The authored `imports` map is preserved.
+
+Exact and wildcard keys, nested conditions, and fallback arrays are supported. Repeated local targets are built once. `null` and package-specifier targets are left to runtime resolution. Local `.mjs` targets require `es`; `.cjs` targets require `cjs`; `.js` targets follow the package `type` that pkgbld writes (including an inferred `"module"` for an ESM-only build). Percent-encoded target paths refer to their decoded filenames, and URL query or fragment suffixes remain in the authored map without becoming part of the output filename. A target whose format is excluded by `--formats`, whose source is missing, or whose output path is invalid or conflicts with another entry fails the build with its manifest location. Local assets and `.d.ts` targets are not generated by this JavaScript entry process; supply them through their own producer.
+
+Keys beginning `#/` work on Node.js 24.14+ and 25.4+; older supported Node.js versions reject those specifiers at runtime. Use names such as `#utils` when supporting Node.js 20.
+
 ## CLI options
 
 ### umd
@@ -83,7 +107,9 @@ Supported targets for this option: `es`, `cjs` and `umd`.
 pkgbld --formats=es
 ```
 
-Defines what formats to build, only supports `es` and `cjs` at the moment. Use `umd` flag to build umd target.
+Defines what formats to build: `es`, `cjs`, and `umd`. Use `--umd` to select UMD entry points.
+
+Private import targets must have their required format included here. They are emitted at their declared paths independently of the output filename patterns below.
 
 ### preprocess
 
@@ -131,6 +157,24 @@ pkgbld --include-externals=lodash
 
 Bundles all or specified externals into a package.
 
+This does not inline this package's own `#` imports when package-import handling is enabled. A bundled dependency's `#` imports are resolved against that dependency's map.
+
+### no-imports
+
+```
+pkgbld --no-imports
+```
+
+Disables local target discovery and `#` externalization for this package. The authored `imports` map is preserved. This restores the earlier source-import behavior and does not affect `--conditions`.
+
+### conditions
+
+```
+pkgbld --conditions=node,development
+```
+
+Adds build-time conditions when resolving bundled dependencies, including their `#` imports. Comma-separated values supplement the resolver's built-in conditions. With no flag, the resolver keeps its existing implicit `production` condition, or `development` when selected by `NODE_ENV`. The order of keys in a dependency's map determines which matching branch wins. These conditions do not choose which branches of this package's own `imports` map are built.
+
 ### eject
 
 ```
@@ -200,7 +244,7 @@ pkgbld --no-exports
 Do not add exports field in package.json.
 
 This also disables entry-point discovery from an existing `exports` field. Only the top-level `src/index` entry point is built
-unless a plugin provides additional inputs.
+unless a plugin provides additional inputs or enabled package imports declare local JavaScript targets.
 
 ## Build plugin interface
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0",
+  "version": "2.1.0",
   "name": "pkgbld",
   "license": "MIT",
   "author": "Konstantin Shutkin",

package/src/build-configuration.js

@@ -101,6 +101,10 @@ function createDefaultDraft() {
             includeExternals: defaults.includeExternals,
             removeLegalComments: false,
         },
+        resolution: {
+            imports: defaults.imports,
+            conditions: [...defaults.conditions],
+        },
         packageJson: {
             update: true,
             format: defaults.formatPackageJson,
@@ -124,6 +128,9 @@ function createDefaultDraft() {
  * @param {PackageJson} packageJson
  */
 function applyPackageMetadata(draft, packageJson) {
+    if (packageJson.imports !== undefined) {
+        draft.resolution.imports = true;
+    }
     if (typeof packageJson.umd === 'string') {
         draft.outputs.umdEntries.push('index');
         draft.outputs.formats.push('umd');
@@ -186,6 +193,8 @@ function applyCli(draft, flags, provided) {
     if (provided.includeExternals) {
         draft.transforms.includeExternals = /** @type {boolean | string[]} */ (flags.includeExternals);
     }
+    if (provided.imports) draft.resolution.imports = /** @type {boolean} */ (flags.imports);
+    if (provided.conditions) draft.resolution.conditions = [.../** @type {string[]} */ (flags.conditions)];
     if (provided.eject) draft.execution.eject = /** @type {boolean} */ (flags.eject);
     if (provided.tsConfig) draft.typescript.updateConfig = /** @type {boolean} */ (flags.tsConfig);
     if (provided.updatePackageJson) draft.packageJson.update = /** @type {boolean} */ (flags.updatePackageJson);
@@ -209,6 +218,7 @@ function normalize(draft) {
     if (Array.isArray(draft.outputs?.sourcemaps)) draft.outputs.sourcemaps = unique(draft.outputs.sourcemaps);
     if (Array.isArray(draft.transforms?.compress)) draft.transforms.compress = unique(draft.transforms.compress);
     if (Array.isArray(draft.transforms?.preprocess)) draft.transforms.preprocess = unique(draft.transforms.preprocess);
+    if (Array.isArray(draft.resolution?.conditions)) draft.resolution.conditions = unique(draft.resolution.conditions);
     if (Array.isArray(draft.transforms.includeExternals)) {
         draft.transforms.includeExternals = unique(draft.transforms.includeExternals);
     }
@@ -240,6 +250,7 @@ function validate(draft, packageJson) {
     validateFormats(draft.transforms.compress, 'transforms.compress', issues);
     validateStrings(draft.outputs.umdEntries, 'outputs.umdEntries', issues);
     validateStrings(draft.transforms.preprocess, 'transforms.preprocess', issues);
+    validateStrings(draft.resolution.conditions, 'resolution.conditions', issues);
     if (draft.outputs.umdEntries.length > 0 && typeof packageJson.name !== 'string') {
         issues.push({ code: 'PACKAGE_NAME_REQUIRED', path: 'package.name', message: 'a package name is required for UMD entries' });
     }

package/src/build-entries.js

@@ -10,9 +10,10 @@ import { isExists } from './helpers.js';
  * @typedef {import('./types.js').BuildEntryContributions} BuildEntryContributions
  * @typedef {import('./types.js').BuildEntryIssue} BuildEntryIssue
  * @typedef {import('./types.js').BuildFormat} BuildFormat
+ * @typedef {import('./types.js').ImportTarget} ImportTarget
  */
 
-const sourceFileExtensions = /** @type {const} */ (['ts', 'tsx', 'js', 'jsx', 'cjs', 'mjs']);
+export const sourceFileExtensions = /** @type {const} */ (['ts', 'tsx', 'js', 'jsx', 'cjs', 'mjs']);
 
 export class BuildEntryError extends Error {
     /** @param {BuildEntryIssue[]} issues */
@@ -28,18 +29,25 @@ export class BuildEntryError extends Error {
  * one immutable catalog.
  *
  * @param {readonly string[]} packageEntryNames
+ * @param {readonly ImportTarget[]} importTargets
  * @param {BuildConfiguration} configuration
  * @param {(contributions: BuildEntryContributions) => void} contribute
  * @returns {Promise<BuildEntries>}
  */
-export async function resolveBuildEntries(packageEntryNames, configuration, contribute) {
-    /** @type {(BuildEntryContribution & { issuePath: string })[]} */
-    const specifications = packageEntryNames.map((name, index) => ({ name, issuePath: `package.entries[${index}]` }));
+export async function resolveBuildEntries(packageEntryNames, importTargets, configuration, contribute) {
+    /** @type {(BuildEntryContribution & { issuePath: string; origin: 'export' | 'plugin'; manifestPath: string })[]} */
+    const specifications = packageEntryNames.map((name, index) => ({
+        name,
+        issuePath: `package.entries[${index}]`,
+        origin: 'export',
+        manifestPath: `package.exports[${JSON.stringify(name === 'index' ? '.' : `./${name}`)}]`,
+    }));
     let contributionIndex = 0;
     const contributions = {
         /** @param {BuildEntryContribution} contribution */
         add(contribution) {
-            specifications.push({ ...contribution, issuePath: `plugins.entries[${contributionIndex}]` });
+            const issuePath = `plugins.entries[${contributionIndex}]`;
+            specifications.push({ ...contribution, issuePath, origin: 'plugin', manifestPath: issuePath });
             contributionIndex += 1;
         },
     };
@@ -87,6 +95,8 @@ export async function resolveBuildEntries(packageEntryNames, configuration, cont
         }
         const entry = Object.freeze({
             name,
+            origin: specification.origin,
+            manifestPath: specification.manifestPath,
             sourcePath: source.sourcePath,
             extension: source.extension,
             outputPaths: Object.freeze(outputPaths),
@@ -95,13 +105,47 @@ export async function resolveBuildEntries(packageEntryNames, configuration, cont
         byName.set(name, entry);
     }
 
+    for (const target of importTargets) {
+        const name = `@imports/${target.outputPath.slice(2)}`;
+        if (byName.has(name)) {
+            issues.push({
+                code: 'DUPLICATE_BUILD_ENTRY',
+                path: target.issuePath,
+                name,
+                message: `Build entry ${JSON.stringify(name)} is declared more than once`,
+            });
+            continue;
+        }
+        const source = await resolveSource(target.sourceName, undefined, configuration.paths.sourceDir);
+        if (!source) {
+            issues.push({
+                code: 'SOURCE_NOT_FOUND',
+                path: target.issuePath,
+                name,
+                message: `Import target ${JSON.stringify(target.outputPath)} has no supported source file`,
+            });
+            continue;
+        }
+        const entry = Object.freeze({
+            name,
+            origin: /** @type {const} */ ('import'),
+            manifestPath: target.issuePath,
+            sourcePath: source.sourcePath,
+            extension: source.extension,
+            outputPaths: Object.freeze({ [target.format]: target.outputPath }),
+        });
+        values.push(entry);
+        byName.set(name, entry);
+    }
+
     validateSelections(byName, configuration.outputs.umdEntries, 'outputs.umdEntries', issues);
     validateSelections(byName, configuration.transforms.preprocess, 'transforms.preprocess', issues);
-    validateOutputPaths(values, issues);
+    const shared = validateOutputPaths(values, issues);
 
     if (issues.length > 0) throw new BuildEntryError(issues);
 
-    const frozenValues = Object.freeze(values);
+    for (const entry of shared) byName.delete(entry.name);
+    const frozenValues = Object.freeze(values.filter(entry => !shared.has(entry)));
     return Object.freeze({
         values: frozenValues,
         /** @param {string} name */
@@ -113,7 +157,7 @@ export async function resolveBuildEntries(packageEntryNames, configuration, cont
                         code: 'SELECTED_BUILD_ENTRY_NOT_FOUND',
                         path: 'entries',
                         name,
-                        message: `Build entry ${JSON.stringify(name)} was not discovered; available entries: ${values.map(entry => entry.name).join(', ')}`,
+                        message: `Build entry ${JSON.stringify(name)} was not discovered; available entries: ${frozenValues.map(entry => entry.name).join(', ')}`,
                     },
                 ]);
             }
@@ -195,20 +239,33 @@ function validateSelections(byName, names, selectionPath, issues) {
  * @param {BuildEntryIssue[]} issues
  */
 function validateOutputPaths(entries, issues) {
+    /** @type {Map<string, { entry: BuildEntry; format: string }>} */
     const owners = new Map();
+    /** @type {Set<BuildEntry>} */
+    const shared = new Set();
     for (const entry of entries) {
         for (const [format, outputPath] of Object.entries(entry.outputPaths)) {
-            const owner = owners.get(outputPath);
+            const normalizedPath = path.resolve(outputPath);
+            const owner = owners.get(normalizedPath);
             if (owner) {
-                issues.push({
-                    code: 'OUTPUT_PATH_COLLISION',
-                    path: `entries.${entry.name}.outputPaths.${format}`,
-                    name: entry.name,
-                    message: `Output path ${JSON.stringify(outputPath)} is also produced by Build entry ${JSON.stringify(owner)}`,
-                });
+                if (
+                    entry.origin === 'import' &&
+                    owner.format === format &&
+                    path.resolve(entry.sourcePath) === path.resolve(owner.entry.sourcePath)
+                ) {
+                    shared.add(entry);
+                } else {
+                    issues.push({
+                        code: 'OUTPUT_PATH_COLLISION',
+                        path: entry.manifestPath,
+                        name: entry.name,
+                        message: `Output path ${JSON.stringify(outputPath)} conflicts with ${owner.entry.manifestPath}`,
+                    });
+                }
             } else {
-                owners.set(outputPath, entry.name);
+                owners.set(normalizedPath, { entry, format });
             }
         }
     }
+    return shared;
 }

package/src/builtin-plugins/externals.js

@@ -26,7 +26,7 @@ export function curry(fn, ...args) {
  * @param {PackageProcessingResult} packageResult
  */
 export default async function (provider, configuration, packageResult) {
-    const inputs = packageResult.entries.values.map(entry => entry.sourcePath);
+    const inputs = packageResult.entries.values.filter(entry => entry.origin !== 'import').map(entry => entry.sourcePath);
     if (configuration.transforms.includeExternals === true) {
         return;
     }
@@ -42,7 +42,7 @@ export default async function (provider, configuration, packageResult) {
         provider.provide(
             () =>
                 pluginExternals(
-                    configuration.transforms.includeExternals === false
+                    configuration.transforms.includeExternals === false && !configuration.resolution.imports
                         ? {}
                         : (/** @type {string} */ id, /** @type {boolean} */ external, /** @type {string} */ importer) =>
                               includeExternals(importer, external, id, configuration)
@@ -86,6 +86,7 @@ export default async function (provider, configuration, packageResult) {
  * @param {BuildConfiguration} configuration
  */
 function includeExternals(_importer, external, id, configuration) {
+    if (configuration.resolution.imports && id.startsWith('#')) return false;
     if (configuration.transforms.includeExternals === false) return external;
     if (!external) return false;
     const internals = /** @type {readonly string[]} */ (configuration.transforms.includeExternals);

package/src/builtin-plugins/package-imports.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ */
+export default function (provider, configuration) {
+    if (!configuration.resolution.imports) return;
+
+    provider.globalImport('node:fs/promises', 'fs');
+    provider.globalImport('path', 'path');
+    const createPlugin = /** @type {typeof createPackageImportsPlugin} */ (
+        provider.globalSetup(createPackageImportsPlugin) ?? createPackageImportsPlugin
+    );
+    provider.provide(() => createPlugin(), Priority.packageImports);
+}
+
+/**
+ * Keep the package's private specifiers for runtime resolution. Each importer
+ * is assigned to its nearest real package boundary, so linked dependencies and
+ * nested workspace packages retain ownership of their own private imports.
+ */
+export function createPackageImportsPlugin() {
+    const packageRoot = fs.realpath(process.cwd());
+    /** @type {Map<string, string | null>} */
+    const owners = new Map();
+    return {
+        name: 'pkgbld:package-imports',
+        /** @param {string} id @param {string | undefined} importer */
+        async resolveId(id, importer) {
+            if (!id.startsWith('#') || !importer || importer.includes('\0')) return null;
+            let realImporter;
+            try {
+                realImporter = await fs.realpath(importer.split('?', 1)[0]);
+            } catch (error) {
+                if (['ENOENT', 'EINVAL'].includes(/** @type {NodeJS.ErrnoException} */ (error).code ?? '')) return null;
+                throw error;
+            }
+            const owner = await findOwner(path.dirname(realImporter));
+            return owner === (await packageRoot) ? { id, external: true } : null;
+        },
+    };
+
+    /** @param {string} start */
+    async function findOwner(start) {
+        let directory = start;
+        /** @type {string[]} */
+        const visited = [];
+        while (true) {
+            if (owners.has(directory)) {
+                const owner = /** @type {string | null} */ (owners.get(directory));
+                for (const visitedDirectory of visited) owners.set(visitedDirectory, owner);
+                return owner;
+            }
+            visited.push(directory);
+            try {
+                await fs.access(path.join(directory, 'package.json'));
+                for (const visitedDirectory of visited) owners.set(visitedDirectory, directory);
+                return directory;
+            } catch (error) {
+                if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error;
+            }
+            const parent = path.dirname(directory);
+            if (parent === directory) {
+                for (const visitedDirectory of visited) owners.set(visitedDirectory, null);
+                return null;
+            }
+            directory = parent;
+        }
+    }
+}

package/src/builtin-plugins/resolve.js

@@ -2,13 +2,21 @@ import { Priority } from '../priorities.js';
 
 /**
  * @typedef {import('../types.js').Provider} Provider
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
  */
 
 /**
  * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
  */
-export default async function (provider) {
+export default async function (provider, configuration) {
     const pluginResolve = await provider.import('@rollup/plugin-node-resolve');
 
-    provider.provide(() => pluginResolve(), Priority.resolve);
+    provider.provide(
+        () =>
+            configuration.resolution.conditions.length > 0
+                ? pluginResolve({ exportConditions: [...configuration.resolution.conditions] })
+                : pluginResolve(),
+        Priority.resolve
+    );
 }

package/src/get-plugins.js

@@ -3,6 +3,7 @@ import clean from './builtin-plugins/clean.js';
 import commonjs from './builtin-plugins/commonjs.js';
 import externals from './builtin-plugins/externals.js';
 import json from './builtin-plugins/json.js';
+import packageImports from './builtin-plugins/package-imports.js';
 import preprocess from './builtin-plugins/preprocess.js';
 import resolve from './builtin-plugins/resolve.js';
 import terser from './builtin-plugins/terser.js';
@@ -12,7 +13,7 @@ import terser from './builtin-plugins/terser.js';
  * @typedef {import('./types.js').Provider} Provider
  */
 
-export const plugins = [clean, commonjs, externals, preprocess, resolve, terser, binify, json];
+export const plugins = [clean, commonjs, externals, preprocess, packageImports, resolve, terser, binify, json];
 
 const noop = () => undefined;
 

package/src/get-rollup-configs.js

@@ -1,3 +1,5 @@
+import path from 'node:path';
+
 import refiner from '@slimlib/refine-partition';
 
 import { plugins as pluginFactories } from './get-plugins.js';
@@ -21,8 +23,11 @@ import { areSetsEqual, toArray } from './helpers.js';
  * @param {BuildPluginLifecycle} pluginLifecycle
  */
 export async function getRollupConfigs([provider, plugins], packageResult, configuration, helpers, pluginLifecycle) {
-    const inputs = packageResult.entries.values.map(entry => entry.sourcePath);
-    const entriesBySourcePath = new Map(packageResult.entries.values.map(entry => [entry.sourcePath, entry]));
+    const publicEntries = packageResult.entries.values.filter(entry => entry.origin !== 'import');
+    const privateEntries = packageResult.entries.values.filter(entry => entry.origin === 'import');
+    const inputs = publicEntries.map(entry => entry.sourcePath);
+    const publicInputSet = new Set(inputs);
+    const entriesBySourcePath = new Map(publicEntries.map(entry => [entry.sourcePath, entry]));
     const factoryInProgress = [];
 
     const fileNamePatterns = /** @type {{ [key in InternalModuleFormat]: string }} */ ({
@@ -43,7 +48,7 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
     const expandInputs = new Set();
 
     for (const plugin of plugins) {
-        if (plugin.format && plugin.inputs?.length && !plugin.outputPlugin) {
+        if (plugin.format && plugin.inputs?.some(input => publicInputSet.has(input)) && !plugin.outputPlugin) {
             for (const format of toArray(plugin.format)) {
                 expandInputs.add(format);
             }
@@ -56,6 +61,8 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
 
     for (const plugin of plugins) {
         if (plugin.format && !plugin.outputPlugin) {
+            const publicPluginInputs = plugin.inputs?.filter(input => publicInputSet.has(input));
+            if (plugin.inputs && publicPluginInputs?.length === 0) continue;
             const formats = toArray(plugin.format);
             if (!plugin.inputs || plugin.inputs.length === 0) {
                 refineNext(doExpandInputs(formats));
@@ -64,7 +71,7 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
             } else {
                 const expanded = [];
                 for (const format of formats) {
-                    for (const input of plugin.inputs) {
+                    for (const input of /** @type {string[]} */ (publicPluginInputs)) {
                         expanded.push(`${format}.${input}`);
                     }
                 }
@@ -124,7 +131,7 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
         partitions.push({ formats: [...mapFormatInputs.keys()], inputs: [.../** @type {Set<string>} */ (prevInputs)] });
     }
 
-    return partitions.map(({ formats, inputs }) => {
+    const publicConfigs = partitions.map(({ formats, inputs }) => {
         return {
             input: Object.fromEntries(
                 inputs.map(input => [/** @type {import('./types.js').BuildEntry} */ (entriesBySourcePath.get(input)).name, input])
@@ -143,6 +150,30 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
         };
     });
 
+    const privateConfigs = privateEntries.map(entry => {
+        const [[format, outputPath]] = Object.entries(entry.outputPaths);
+        const input = entry.sourcePath;
+        const selectedFormat = /** @type {InternalModuleFormat} */ (format);
+        return {
+            input,
+            output: [
+                {
+                    format: selectedFormat,
+                    dir: configuration.paths.outputDir,
+                    entryFileNames: path
+                        .relative(path.resolve(configuration.paths.outputDir), path.resolve(outputPath))
+                        .replaceAll('\\', '/'),
+                    plugins: getPlugins([selectedFormat], [input], true, true),
+                    sourcemap: configuration.outputs.sourcemaps.includes(/** @type {import('./types.js').BuildFormat} */ (selectedFormat)),
+                    ...getExtraOutputSettings(selectedFormat, [input]),
+                },
+            ],
+            plugins: getPlugins([selectedFormat], [input], false, true),
+        };
+    });
+
+    return [...publicConfigs, ...privateConfigs];
+
     /**
      * @param {InternalModuleFormat} format
      * @param {string[]} inputs
@@ -176,14 +207,20 @@ export async function getRollupConfigs([provider, plugins], packageResult, confi
      * @param {InternalModuleFormat[]} formats
      * @param {string[]} inputs
      * @param {boolean} outputPlugin
+     * @param {boolean} [privateOutput]
      */
-    function getPlugins(formats, inputs, outputPlugin) {
+    function getPlugins(formats, inputs, outputPlugin, privateOutput = false) {
         const filteredPlugins = [];
         for (const plugin of plugins) {
             if (!!plugin.outputPlugin === outputPlugin) {
+                const publicPluginInputs = plugin.inputs?.filter(input => publicInputSet.has(input));
                 if (
                     (!plugin.format || toArray(plugin.format).some(format => formats.includes(format))) &&
-                    (!plugin.inputs || plugin.inputs.every(input => inputs.includes(input)))
+                    (!plugin.inputs ||
+                        plugin.inputs.length === 0 ||
+                        (privateOutput
+                            ? plugin.inputs.some(input => inputs.includes(input))
+                            : publicPluginInputs?.length > 0 && publicPluginInputs.every(input => inputs.includes(input))))
                 ) {
                     filteredPlugins.push({
                         instance: plugin.plugin(),

package/src/options/index.js

@@ -59,6 +59,8 @@ export const cliFlagsDefaults = {
     src: 'src',
     bin: /** @type {string[] | undefined} */ (undefined),
     includeExternals: /** @type {boolean | string[]} */ (false),
+    imports: false,
+    conditions: /** @type {string[]} */ ([]),
     eject: false,
     tsConfig: false,
     updatePackageJson: true,
@@ -118,6 +120,15 @@ export const cliFlags = {
         description: 'Include all/specified externals into the result bundle(s)',
         optionalValue: true,
     },
+    imports: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Build and preserve package imports',
+        default: cliFlagsDefaults.imports,
+    },
+    conditions: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Additional conditions for resolving bundled dependencies',
+    },
     eject: {
         type: /** @type {'boolean'} */ ('boolean'),
         description: 'Eject config',

package/src/package-imports.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { BuildEntryError, sourceFileExtensions } from './build-entries.js';
+
+/**
+ * @typedef {import('./types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('./types.js').BuildEntryIssue} BuildEntryIssue
+ * @typedef {import('./types.js').ImportTarget} ImportTarget
+ * @typedef {import('./types.js').BuildFormat} BuildFormat
+ */
+
+const javascriptExtensions = new Set(['.js', '.mjs', '.cjs']);
+
+/**
+ * Find every local JavaScript leaf of an authored package imports map.
+ * Non-JavaScript and package-specifier leaves remain the responsibility of
+ * their runtime resolver or producer.
+ *
+ * @param {unknown} imports
+ * @param {BuildConfiguration} configuration
+ * @param {unknown} packageType
+ * @returns {Promise<ImportTarget[]>}
+ */
+export async function collectPackageImportTargets(imports, configuration, packageType) {
+    if (imports === undefined || !configuration.resolution.imports) return [];
+
+    /** @type {BuildEntryIssue[]} */
+    const issues = [];
+    /** @type {Map<string, ImportTarget>} */
+    const targets = new Map();
+    const leaves = parseImportMap(imports, issues);
+    for (const leaf of leaves) {
+        for (const target of await expandLocalTarget(leaf, configuration, packageType, issues)) {
+            if (!targets.has(target.outputPath)) targets.set(target.outputPath, target);
+        }
+    }
+
+    if (issues.length > 0) throw new BuildEntryError(issues);
+    return [...targets.values()];
+}
+
+/**
+ * Walk the authored map without selecting runtime conditions. Every local
+ * branch may need its own output, while package specifiers remain mappings.
+ * @param {unknown} imports
+ * @param {BuildEntryIssue[]} issues
+ */
+function parseImportMap(imports, issues) {
+    /** @type {{ value: string; issuePath: string; wildcardKey: boolean }[]} */
+    const leaves = [];
+    if (!isRecord(imports)) {
+        issues.push({ code: 'INVALID_IMPORT_MAP', path: 'package.imports', message: 'must be an object' });
+        return leaves;
+    }
+
+    for (const [key, value] of Object.entries(imports)) {
+        const issuePath = `package.imports[${JSON.stringify(key)}]`;
+        const stars = key.match(/\*/g)?.length ?? 0;
+        if (!key.startsWith('#') || key === '#' || key.endsWith('/') || stars > 1) {
+            issues.push({ code: 'INVALID_IMPORT_KEY', path: issuePath, message: `Invalid package import key ${JSON.stringify(key)}` });
+            continue;
+        }
+        visit(value, issuePath, stars > 0);
+    }
+    return leaves;
+
+    /** @param {unknown} value @param {string} issuePath @param {boolean} wildcardKey */
+    function visit(value, issuePath, wildcardKey) {
+        if (value === null) return;
+        if (Array.isArray(value)) {
+            for (const [index, leaf] of value.entries()) visit(leaf, `${issuePath}[${index}]`, wildcardKey);
+            return;
+        }
+        if (isRecord(value)) {
+            for (const [condition, leaf] of Object.entries(value)) {
+                if (isArrayIndex(condition)) {
+                    issues.push({
+                        code: 'INVALID_IMPORT_CONDITION',
+                        path: `${issuePath}.${condition}`,
+                        message: `Integer condition key ${JSON.stringify(condition)} is invalid in a package imports map`,
+                    });
+                } else {
+                    visit(leaf, `${issuePath}.${condition}`, wildcardKey);
+                }
+            }
+            return;
+        }
+        if (typeof value !== 'string') {
+            issues.push({ code: 'INVALID_IMPORT_TARGET', path: issuePath, message: 'must be a string, null, array, or condition object' });
+            return;
+        }
+        if (!value.startsWith('./')) {
+            if (value.startsWith('.') || value.startsWith('/') || value.includes('\\') || value.length === 0 || URL.canParse(value)) {
+                issues.push({
+                    code: 'INVALID_IMPORT_TARGET',
+                    path: issuePath,
+                    message: `Invalid package import target ${JSON.stringify(value)}`,
+                });
+            }
+            return;
+        }
+        leaves.push({ value, issuePath, wildcardKey });
+    }
+}
+
+/** @param {string} key */
+function isArrayIndex(key) {
+    return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
+}
+
+/**
+ * Validate a local URL target, then expand its output pattern against source
+ * names. Final source-extension selection happens in resolveBuildEntries.
+ * @param {{ value: string; issuePath: string; wildcardKey: boolean }} leaf
+ * @param {BuildConfiguration} configuration
+ * @param {unknown} packageType
+ * @param {BuildEntryIssue[]} issues
+ * @returns {Promise<ImportTarget[]>}
+ */
+async function expandLocalTarget({ value, issuePath, wildcardKey }, configuration, packageType, issues) {
+    const pathPart = value.split(/[?#]/, 1)[0];
+    const rawSegments = pathPart.slice(2).split('/');
+    let outputPath;
+    try {
+        if (
+            pathPart.includes('\\') ||
+            rawSegments.some(segment => {
+                const decoded = decodeURIComponent(segment);
+                return (
+                    decoded === '' ||
+                    decoded === '.' ||
+                    decoded === '..' ||
+                    decoded.toLowerCase() === 'node_modules' ||
+                    decoded.includes('/') ||
+                    decoded.includes('\\')
+                );
+            })
+        ) {
+            throw new Error('invalid path segment');
+        }
+        outputPath = fileURLToPath(new URL(value, pathToFileURL(path.join(process.cwd(), 'package.json'))));
+    } catch {
+        issues.push({
+            code: 'INVALID_IMPORT_TARGET',
+            path: issuePath,
+            message: `Invalid local package import target ${JSON.stringify(value)}`,
+        });
+        return [];
+    }
+
+    const extension = path.extname(outputPath);
+    if (!javascriptExtensions.has(extension)) return [];
+
+    const outputDir = path.resolve(configuration.paths.outputDir);
+    if (!outputPath.startsWith(`${outputDir}${path.sep}`) || (pathPart.includes('*') && !wildcardKey)) {
+        issues.push({
+            code: 'INVALID_IMPORT_TARGET',
+            path: issuePath,
+            message: `Local JavaScript target ${JSON.stringify(value)} must be a safe path beneath ${configuration.paths.outputDir}`,
+        });
+        return [];
+    }
+
+    const format = /** @type {BuildFormat} */ (
+        extension === '.mjs' ? 'es' : extension === '.cjs' ? 'cjs' : packageType === 'module' ? 'es' : 'cjs'
+    );
+    if (!configuration.outputs.formats.includes(format)) {
+        issues.push({
+            code: 'EXCLUDED_IMPORT_FORMAT',
+            path: issuePath,
+            message: `Local target ${JSON.stringify(value)} requires ${format}, which is excluded by outputs.formats`,
+        });
+        return [];
+    }
+
+    const relativeOutput = path.relative(outputDir, outputPath).replaceAll('\\', '/');
+    const sourceName = relativeOutput.slice(0, -extension.length);
+    if (pathPart.includes('*')) {
+        const sourceNames = await findMatchingSourceNames(configuration.paths.sourceDir, sourceName);
+        if (sourceNames.length === 0) {
+            issues.push({
+                code: 'SOURCE_NOT_FOUND',
+                path: issuePath,
+                message: `Import target ${JSON.stringify(value)} has no supported source file`,
+            });
+        }
+        return sourceNames.map(matchedName => ({
+            sourceName: matchedName,
+            outputPath: `./${configuration.paths.outputDir}/${matchedName}${extension}`,
+            format,
+            issuePath,
+        }));
+    }
+    return [{ sourceName, outputPath: `./${configuration.paths.outputDir}/${relativeOutput}`, format, issuePath }];
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {string} sourceDir @param {string} pattern */
+async function findMatchingSourceNames(sourceDir, pattern) {
+    const parts = pattern.split('*').map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const matcher = new RegExp(
+        `^${parts[0]}(.+?)${parts[1]}${parts
+            .slice(2)
+            .map(part => `\\1${part}`)
+            .join('')}$`
+    );
+    /** @type {Set<string>} */
+    const names = new Set();
+    await walk(sourceDir, '');
+    return [...names].sort();
+
+    /** @param {string} directory @param {string} relative */
+    async function walk(directory, relative) {
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        } catch (error) {
+            if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const nextRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(path.join(directory, entry.name), nextRelative);
+            } else if (entry.isFile()) {
+                const extension = path.posix.extname(nextRelative).slice(1);
+                if (sourceFileExtensions.includes(/** @type {typeof sourceFileExtensions[number]} */ (extension))) {
+                    const name = nextRelative.slice(0, -(extension.length + 1));
+                    if (matcher.test(name)) names.add(name);
+                }
+            }
+        }
+    }
+}

package/src/priorities.js

@@ -1,6 +1,7 @@
 export const Priority = /** @type {const} */ ({
     preprocess: 1000,
     cleanup: 1000,
+    packageImports: 1500,
     externals: 2000,
     resolve: 3000,
     commonjs: 4000,

package/src/process-pkg.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createLogger, LogLevel } from '@niceties/logger';
 
 import { resolveBuildEntries } from './build-entries.js';
+import { collectPackageImportTargets } from './package-imports.js';
 
 /**
  * @typedef {import('type-fest').JsonObject} JsonObject
@@ -42,6 +43,9 @@ export async function processPackage(pkg, configuration, pluginLifecycle) {
         process.exit(-1);
     }
 
+    const finalPackageType = allowEsm && !allowCjs && typeof pkg.type !== 'string' ? 'module' : pkg.type;
+    const importTargets = await collectPackageImportTargets(pkg.imports, configuration, finalPackageType);
+
     if (!Array.isArray(pkg.files)) {
         pkg.files = [];
     }
@@ -71,7 +75,7 @@ export async function processPackage(pkg, configuration, pluginLifecycle) {
         entryNames.push(indexId);
     }
 
-    const entries = await resolveBuildEntries(entryNames, configuration, contributions =>
+    const entries = await resolveBuildEntries(entryNames, importTargets, configuration, contributions =>
         pluginLifecycle.contributeEntries(contributions, configuration)
     );
     const indexEntry = entries.require(indexId);
@@ -171,14 +175,15 @@ export async function processPackage(pkg, configuration, pluginLifecycle) {
             pkg.bin = /** @type {string} */ (executableOutputs[0]);
         }
     } else if (packageJson.executables.mode === 'infer' && allowCjs && entries.values.length > 0) {
+        const executableEntries = entries.values.filter(entry => entry.origin !== 'import');
         if (typeof pkg.bin === 'string') {
-            if (entries.values.some(entry => pkg.bin === entry.outputPaths.cjs)) {
+            if (executableEntries.some(entry => pkg.bin === entry.outputPaths.cjs)) {
                 executableOutputs = [pkg.bin];
             }
         } else if (typeof pkg.bin === 'object' && pkg.bin !== null) {
             executableOutputs = /** @type {string[]} */ (
                 Object.values(pkg.bin).filter(
-                    value => typeof value === 'string' && entries.values.some(entry => value === entry.outputPaths.cjs)
+                    value => typeof value === 'string' && executableEntries.some(entry => value === entry.outputPaths.cjs)
                 )
             );
         }
@@ -189,7 +194,9 @@ export async function processPackage(pkg, configuration, pluginLifecycle) {
             typeof pkg.directories.bin === 'string'
         ) {
             if (path.resolve(pkg.directories.bin) === path.resolve(paths.outputDir)) {
-                executableOutputs.push(...entries.values.flatMap(entry => (entry.outputPaths.cjs == null ? [] : [entry.outputPaths.cjs])));
+                executableOutputs.push(
+                    ...executableEntries.flatMap(entry => (entry.outputPaths.cjs == null ? [] : [entry.outputPaths.cjs]))
+                );
                 executableOutputs = Array.from(new Set(executableOutputs));
             }
         }

package/src/types.js

@@ -60,6 +60,7 @@
  *     includeExternals: boolean | string[];
  *     removeLegalComments: boolean;
  *   };
+ *   resolution: { imports: boolean; conditions: string[] };
  *   packageJson: {
  *     update: boolean;
  *     format: boolean;
@@ -87,6 +88,7 @@
  *     includeExternals: boolean | readonly string[];
  *     removeLegalComments: boolean;
  *   }>;
+ *   resolution: Readonly<{ imports: boolean; conditions: readonly string[] }>;
  *   packageJson: Readonly<{
  *     update: boolean;
  *     format: boolean;
@@ -117,6 +119,8 @@
 /**
  * @typedef {Readonly<{
  *   name: string;
+ *   origin: 'export' | 'import' | 'plugin';
+ *   manifestPath: string;
  *   sourcePath: string;
  *   extension: BuildEntryExtension;
  *   outputPaths: Readonly<Partial<Record<BuildFormat, string>>>;
@@ -125,7 +129,8 @@
 
 /** @typedef {{ name: string; sourcePath?: string }} BuildEntryContribution */
 /** @typedef {{ add(contribution: BuildEntryContribution): void }} BuildEntryContributions */
-/** @typedef {{ code: 'INVALID_BUILD_ENTRY_NAME' | 'DUPLICATE_BUILD_ENTRY' | 'SOURCE_NOT_FOUND' | 'SELECTED_BUILD_ENTRY_NOT_FOUND' | 'OUTPUT_PATH_COLLISION'; path: string; message: string; name?: string }} BuildEntryIssue */
+/** @typedef {{ sourceName: string; outputPath: string; format: BuildFormat; issuePath: string }} ImportTarget */
+/** @typedef {{ code: 'INVALID_BUILD_ENTRY_NAME' | 'DUPLICATE_BUILD_ENTRY' | 'SOURCE_NOT_FOUND' | 'SELECTED_BUILD_ENTRY_NOT_FOUND' | 'OUTPUT_PATH_COLLISION' | 'INVALID_IMPORT_MAP' | 'INVALID_IMPORT_KEY' | 'INVALID_IMPORT_TARGET' | 'EXCLUDED_IMPORT_FORMAT'; path: string; message: string; name?: string }} BuildEntryIssue */
 
 /**
  * @typedef {Readonly<{

package/types/index.d.ts

@@ -78,6 +78,10 @@ declare module 'pkgbld' {
 			includeExternals: boolean | string[];
 			removeLegalComments: boolean;
 		};
+		resolution: {
+			imports: boolean;
+			conditions: string[];
+		};
 		packageJson: {
 			update: boolean;
 			format: boolean;
@@ -118,6 +122,10 @@ declare module 'pkgbld' {
 			includeExternals: boolean | readonly string[];
 			removeLegalComments: boolean;
 		}>;
+		resolution: Readonly<{
+			imports: boolean;
+			conditions: readonly string[];
+		}>;
 		packageJson: Readonly<{
 			update: boolean;
 			format: boolean;
@@ -149,6 +157,8 @@ declare module 'pkgbld' {
 	type PluginSharedState_1 = Map<unknown, unknown>;
 	type BuildEntry_1 = Readonly<{
 		name: string;
+		origin: "export" | "import" | "plugin";
+		manifestPath: string;
 		sourcePath: string;
 		extension: BuildEntryExtension;
 		outputPaths: Readonly<Partial<Record<BuildFormat_1, string>>>;
@@ -161,7 +171,7 @@ declare module 'pkgbld' {
 		add(contribution: BuildEntryContribution_1): void;
 	};
 	type BuildEntryIssue_1 = {
-		code: "INVALID_BUILD_ENTRY_NAME" | "DUPLICATE_BUILD_ENTRY" | "SOURCE_NOT_FOUND" | "SELECTED_BUILD_ENTRY_NOT_FOUND" | "OUTPUT_PATH_COLLISION";
+		code: "INVALID_BUILD_ENTRY_NAME" | "DUPLICATE_BUILD_ENTRY" | "SOURCE_NOT_FOUND" | "SELECTED_BUILD_ENTRY_NOT_FOUND" | "OUTPUT_PATH_COLLISION" | "INVALID_IMPORT_MAP" | "INVALID_IMPORT_KEY" | "INVALID_IMPORT_TARGET" | "EXCLUDED_IMPORT_FORMAT";
 		path: string;
 		message: string;
 		name?: string;
@@ -245,6 +255,8 @@ declare module 'pkgbld/options' {
 		let src: string;
 		let bin: string[] | undefined;
 		let includeExternals: boolean | string[];
+		let imports: boolean;
+		let conditions: string[];
 		let eject: boolean;
 		let tsConfig: boolean;
 		let updatePackageJson: boolean;