pkgbld 1.36.0 → 2.1.0

package/README.md

@@ -24,7 +24,7 @@ npm install --save-dev pkgbld
 
 1. Start by creating package.json using `npm init`
 2. Add pkgbld `npm install --save-dev pkgbld`
-3. Create `src/index.ts`
+3. Create `src/index.js`
 4. Add pkgbld in the 'scripts' field of your package.json like:
 
 ```json
@@ -35,10 +35,38 @@ npm install --save-dev pkgbld
 
 Run `npm run build`.
 
+For TypeScript or TSX sources, also install
+[`pkgbld-plugin-swc`](https://github.com/kshutkin/package-build/tree/main/pkgbld-plugin-swc).
+`pkgbld` discovers the plugin from your project dependencies and uses SWC to strip types.
+
 ## package.json
 
 `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
@@ -79,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
 
@@ -127,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
 
 ```
@@ -195,102 +243,36 @@ pkgbld --no-exports
 
 Do not add exports field in package.json.
 
-### prune (command)
-
-```
-pkgbld prune
-```
-
-prune devDependencies and redundant scripts from package.json
-
-### prune --profile=<profile>
-
-There are two profiles: `library` and `app`. `library` is default.
-
-Right now it only affects how `prune` command removes entries in the `scripts` field.
+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 or enabled package imports declare local JavaScript targets.
 
-For `library` profile it retains: 'preinstall', 'install', 'postinstall', 'prepublish', 'preprepare', 'prepare', 'postprepare'.
+## Build plugin interface
 
-For `app` profile it retains in addition: 'prestart', 'start', 'poststart', 'prerestart', 'restart', 'postrestart', 'prestop', 'stop', 'poststop', 'pretest', 'test', 'posttest'.
-
-### flatten
-
-```
-pkgbld prune --flatten=<directory>
-```
-
-Flattens file structure by moving all files from `dist` or other directory to the root directory and updating package.json.
-
-If the directory is not specified it is guessed from package.json.
-
-If files cannot be copied because of name conflicts the command will fail.
-
-### removeSourcemaps
-
-```
-pkgbld prune --remove-sourcemaps
-```
-
-Removes all sourcemaps from the package. The logic is very simple and removes all files with `.map` extension and references in format `//# sourceMappingURL=<mapFile>`.
-
-### optimizeFiles (default)
-
-```
-pkgbld prune --optimize-files=false
-```
-
-Optimizes files by removing all files that are not required for pack at the given moment.
-
-You might want to disable this option in some edge cases.
-
-### no-subpackages
-
-```
-pkgbld --no-subpackages
-```
-
-Do not create subpackage directories with package.json files for non-index entry points.
-
-By default, pkgbld creates a directory for each non-index entry point (e.g., `second/package.json` for a `./second` export) to enable simpler imports. Use this flag to disable this behavior.
-
-Note: The `pkgbld-plugin-dts-buddy` plugin automatically sets this flag when loaded, as it provides alternative type resolution through the dts-buddy bundling approach.
-
-### removeLegalComments
-
-```
-pkgbld prune --remove-legal-comments --compress=es,cjs
-```
+`pkgbld` loads plugins named `pkgbld-plugin-*` or `@scope/pkgbld-plugin-*` from
+`dependencies`, `devDependencies`, and `peerDependencies`. The package name after
+the optional scope must start with `pkgbld-plugin-`.
 
-Removes all legal comments from the package. Only works with compress.
+Plugins implement one or more lifecycle methods on the object returned by the plugin module's `create()` function.
 
-## Plugin API
+Build configuration is resolved from defaults, package metadata, and explicit CLI options before `configure` runs. Plugins receive the effective mutable draft and have final authority. After all `configure` hooks finish, `pkgbld` normalizes, validates, and deeply freezes the configuration; every later hook receives that frozen value.
 
-`pkgbld` reads all installed packages named `pkgbld-plugin-*` and assumes they are plugins
+Build entries are resolved after configuration. A plugin that needs to add a source module does so during `contributeEntries`; later phases receive immutable entries containing the canonical name, concrete source path, source extension, and enabled output paths. Configured UMD and preprocessing selections must resolve to discovered Build entries.
 
-Plugins suppose to implement one or more of the following interface methods on an object that returned by `create()` function exported by the plugin module.
+`shared` is mutable state scoped to one build for coordination between plugins. Lifecycle phase boundaries are preserved, but plugin order within one phase is not guaranteed and asynchronous hooks in that phase may run in parallel. Plugins must not depend on the order of same-phase reads and writes. State owned by one plugin should remain in the closure created by `create()`.
 
 ```typescript
 interface PkgbldPlugin {
-  options(
-    parsedArgs: { [key: string]: string | number },
-    options: ReturnType<typeof getCliOptions>
-  ): void;
-  processPackageJson(
-    packageJson: PackageJson,
-    inputs: string[],
-    logger: Logger
-  ): void;
-  processTsConfig(config: Json): void;
-  providePlugins(
-    provider: Provider,
-    config: Record<string, string | string[] | boolean>,
-    inputs: string[]
-  ): Promise<void>;
-  getExtraOutputSettings(
-    format: InternalModuleFormat,
-    inputs: string[]
-  ): Partial<OutputOptions>;
-  buildEnd(): Promise<void>;
+  configure(context: {
+    draft: BuildConfigurationDraft;
+    sources: BuildConfigurationSources;
+    shared: Map<unknown, unknown>;
+  }): void;
+  contributeEntries(context: PluginContributeEntriesContext): void;
+  processPackageJson(context: PluginPackageContext): void;
+  processTsConfig(context: PluginTsConfigContext): void;
+  providePlugins(context: PluginRollupContext): Promise<void>;
+  getExtraOutputSettings(context: PluginOutputContext): Partial<OutputOptions>;
+  buildEnd(context: PluginBuildEndContext): Promise<void>;
 }
 ```
 

package/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-'use strict';
-import('./dist/index.mjs');
+
+import('./src/index.js');

package/package.json

@@ -1,15 +1,23 @@
 {
-  "version": "1.36.0",
+  "version": "2.1.0",
   "name": "pkgbld",
   "license": "MIT",
   "author": "Konstantin Shutkin",
   "bin": "./index.js",
   "type": "module",
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./options": {
+      "types": "./types/index.d.ts",
+      "default": "./src/options/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -28,28 +36,24 @@
     "rollup"
   ],
   "dependencies": {
-    "@niceties/logger": "^1.1.13",
-    "@niceties/draftlog-appender": "^1.3.3",
-    "lodash": "^4.17.21",
-    "rollup": "^4.34.7",
-    "rollup-plugin-typescript2": "^0.36.0",
+    "@niceties/logger": "^2.1.1",
+    "@niceties/draftlog-appender": "^2.1.1",
+    "fast-is-equal": "^1.3.3",
+    "type-fest": "^5.9.0",
+    "rollup": "^4.63.1",
     "rollup-plugin-preprocess": "^0.0.4",
-    "@rollup/plugin-commonjs": "^28.0.2",
-    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.0",
-    "@rollup-extras/plugin-clean": "^1.3.9",
-    "@rollup-extras/plugin-binify": "^1.1.10",
-    "@rollup-extras/plugin-externals": "^1.2.2",
-    "@slimlib/refine-partition": "^1.0.3",
-    "@slimlib/smart-mock": "^0.1.6",
-    "is-builtin-module": "^3.2.1",
-    "terser": "^5.39.0",
-    "kleur": "^4.1.5",
-    "cleye": "^1.3.4",
-    "jsonata": "^2.0.6"
-  },
-  "peerDependencies": {
-    "typescript": ">=5.3.3"
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup-extras/plugin-clean": "^2.0.1",
+    "@rollup-extras/plugin-binify": "^2.0.0",
+    "@rollup-extras/plugin-externals": "^2.0.0",
+    "@slimlib/refine-partition": "^2.0.2",
+    "@slimlib/smart-mock": "^1.0.2",
+    "is-builtin-module": "^5.0.0",
+    "terser": "^5.51.2",
+    "@niceties/ansi": "^1.1.2",
+    "@niceties/node-parseargs-plus": "^0.6.0"
   }
 }