@savvy-web/rslib-builder 0.10.0 → 0.12.0

package/README.md

@@ -8,126 +8,47 @@ Build modern ESM Node.js libraries with minimal configuration. Handles
 TypeScript declarations, package.json transformations, and PNPM workspace
 resolution automatically.
 
-Building TypeScript packages for npm involves repetitive setup: configuring
-bundlers, generating declarations, transforming package.json exports, and
-resolving workspace references. rslib-builder handles these tasks so you can
-focus on your code.
-
 ## Features
 
-- **Zero Config** - Auto-detects entry points from package.json exports
-- **Fast Type Generation** - Uses tsgo (native TypeScript) for 10-100x faster
-  declaration generation
-- **Bundled Declarations** - Rolls up TypeScript types via API Extractor for
-  cleaner public APIs, with multi-entry support for packages with multiple exports
-- **Multi-Target Builds** - Separate dev (source maps) and npm (optimized)
-  outputs
-- **Virtual Entries** - Bundle additional files (like pnpmfile.cjs) with custom
-  output names, bypassing type generation and package.json exports
-- **Flexible Format** - Configure output format (ESM or CJS) at the library level
-  with per-entry overrides for virtual entries
-- **PNPM Integration** - Automatically resolves `catalog:` and `workspace:`
-  references
-- **Package.json Transform** - Converts `.ts` exports to `.js`, generates files
-  array, removes dev-only fields
-- **TSDoc Validation** - Pre-build TSDoc validation with automatic public API discovery
-- **API Model Generation** - Optional API model and resolved tsconfig output for
-  documentation tooling
-- **Extensible** - Add custom RSlib/Rsbuild plugins for advanced use cases
-
-## Prerequisites
-
-- Node.js 24.x or later
-- pnpm 10.x or later
-- TypeScript 5.9.x or later
+- **Zero-Config Entry Detection** - Auto-discovers entry points from package.json
+  exports, no manual configuration needed
+- **10-100x Faster Types** - Uses tsgo (native TypeScript compiler) with API
+  Extractor for bundled, clean public API declarations
+- **Production-Ready Transforms** - Converts `.ts` exports to `.js`, resolves
+  PNPM `catalog:` and `workspace:` references, generates files array
+- **Bundled or Bundleless** - Choose single-file bundles per entry or
+  bundleless mode that preserves your source file structure
+- **Multi-Target Builds** - Separate dev (with source maps) and npm (optimized)
+  outputs from a single configuration
+- **TSDoc Validation** - Pre-build documentation validation with automatic
+  public API discovery
 
 ## Installation
 
 ```bash
-pnpm add -D @savvy-web/rslib-builder
-```
-
-### Peer Dependencies
-
-Install the required peer dependencies:
-
-```bash
-pnpm add -D @rslib/core @microsoft/api-extractor @typescript/native-preview
+npm install --save-dev @savvy-web/rslib-builder @rslib/core @microsoft/api-extractor @typescript/native-preview
 ```
 
 ## Quick Start
 
-Extend the provided tsconfig for optimal settings:
-
-```jsonc
-// tsconfig.json
-{
-  "extends": "@savvy-web/rslib-builder/tsconfig/ecma/lib.json"
-}
-```
-
-Create an `rslib.config.ts` in your project root:
-
 ```typescript
+// rslib.config.ts
 import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
 
 export default NodeLibraryBuilder.create({
   externals: ['@rslib/core'],
-  transform({ pkg, target }) {
-    if (target === 'npm') {
-      delete pkg.devDependencies;
-    }
-    return pkg;
-  },
 });
 ```
 
-Add scripts to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "build": "rslib build --env-mode dev",
-    "build:npm": "rslib build --env-mode npm"
-  }
-}
-```
+Build with `rslib build --env-mode dev` or `rslib build --env-mode npm`.
 
 ## Documentation
 
-For detailed documentation, see the [docs/](./docs/) directory:
-
-- [Getting Started](./docs/guides/getting-started.md) - Installation and setup
-- [Configuration](./docs/guides/configuration.md) - All options explained
-- [Plugin System](./docs/guides/plugins.md) - Built-in and custom plugins
-- [Architecture](./docs/architecture/overview.md) - How it works internally
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
-
-## Example
-
-This package builds itself using its own `NodeLibraryBuilder`. See
-[`rslib.config.ts`](./rslib.config.ts) for a production example.
-
-## Support
-
-This software is provided as-is under the MIT License with no warranty or
-support guarantees. While we welcome bug reports and feature requests via
-GitHub Issues, we cannot guarantee response times or resolution.
-
-For security vulnerabilities, please see [SECURITY.md](./SECURITY.md).
-
-## Links
-
-- [RSlib Documentation](https://rslib.dev/)
-- [Rsbuild Plugin API](https://rsbuild.dev/plugins/dev/core)
-- [API Extractor](https://api-extractor.com/)
-- [PNPM Workspace](https://pnpm.io/workspaces)
-- [PNPM Catalogs](https://pnpm.io/catalogs)
+For configuration options, API reference, and advanced usage, see [docs](./docs/).
 
 ## Contributing
 
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup
-and guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 

package/index.d.ts

@@ -62,10 +62,9 @@ import ts from 'typescript';
  * API model generation is enabled by default. To disable, set `apiModel: false`.
  * Providing an options object implicitly enables API model generation.
  *
- * API models are only generated for the main "index" entry point (the "." export).
- * Additional entry points like "./hooks" or "./utils" do not generate separate API models.
- * This prevents multiple conflicting API models and ensures a single source of truth
- * for package documentation.
+ * When a package has multiple entry points, API Extractor runs for each entry and the
+ * resulting per-entry models are merged into a single API model with multiple
+ * EntryPoint members. Canonical references are scoped per entry point.
  *
  * @public
  */
@@ -222,6 +221,18 @@ export declare interface AutoEntryPluginOptions {
      * @defaultValue false
      */
     exportsAsIndexes?: boolean;
+    /**
+     * When enabled, uses import graph analysis to discover all reachable files
+     * from entry points, and sets RSlib's source.entry to the traced file list
+     * instead of named entries.
+     *
+     * @remarks
+     * Named entries are still exposed via the `entrypoints` map for DtsPlugin
+     * and PackageJsonTransformPlugin to use.
+     *
+     * @defaultValue false
+     */
+    bundleless?: boolean;
 }
 
 /**
@@ -515,24 +526,14 @@ export declare interface ExtractedEntries {
      * Entry name to TypeScript source path mapping.
      */
     entries: Record<string, string>;
+    /**
+     * Entry name to original export key mapping.
+     * Maps entry names back to the original package.json export path
+     * (e.g., `"nested-one"` → `"./nested/one"`).
+     */
+    exportPaths: Record<string, string>;
 }
 
-/**
- * Extracts TypeScript entry points from package.json (functional interface).
- *
- * @remarks
- * This is a convenience function that creates an EntryExtractor instance
- * and extracts entries in one call. For repeated use, consider creating
- * an EntryExtractor instance directly.
- *
- * @param packageJson - The package.json object to extract entries from
- * @param options - Configuration options for entry extraction
- * @returns Object containing the extracted entries
- *
- * @public
- */
-export declare function extractEntriesFromPackageJson(packageJson: PackageJson, options?: EntryExtractorOptions): ExtractedEntries;
-
 /**
  * Plugin to manage the `files` array in package.json for npm publishing.
  *
@@ -1162,6 +1163,7 @@ export declare class NodeLibraryBuilder {
         targets: ("dev" | "npm")[];
         externals: never[];
         apiModel: true;
+        bundle: true;
     };
     /**
      * Merges user-provided options with default options.
@@ -1206,6 +1208,27 @@ export declare class NodeLibraryBuilder {
 }
 
 /**
+ * Configuration options for the NodeLibraryBuilder.
+ *
+ * @remarks
+ * All options are optional with sensible defaults. The most commonly customized options are:
+ * - `externals`: For dependencies that should remain external
+ * - `dtsBundledPackages`: For inlining type definitions
+ * - `transform`: For custom package.json modifications
+ *
+ * @example
+ * ```typescript
+ * import type { NodeLibraryBuilderOptions } from '@savvy-web/rslib-builder';
+ *
+ * const options: NodeLibraryBuilderOptions = {
+ *   externals: ['@rslib/core'],
+ *   dtsBundledPackages: ['picocolors'],
+ *   apiModel: {
+ *     localPaths: ['../docs/packages/my-package'],
+ *   },
+ * };
+ * ```
+ *
  * @public
  */
 export declare interface NodeLibraryBuilderOptions {
@@ -1287,11 +1310,46 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     exportsAsIndexes?: boolean;
+    /**
+     * Patterns for files to copy to the output directory.
+     *
+     * @remarks
+     * Supports both string paths and detailed configuration objects.
+     * A `public/` directory in the project root is automatically added if it exists.
+     *
+     * @defaultValue `[]`
+     */
     copyPatterns: (string | CopyPatternConfig)[];
-    /** Additional plugins */
+    /**
+     * Additional Rsbuild plugins to include in the build.
+     *
+     * @remarks
+     * These plugins run after the built-in plugins (AutoEntryPlugin, DtsPlugin, etc.).
+     *
+     * @defaultValue `[]`
+     */
     plugins: RsbuildPlugin[];
+    /**
+     * Compile-time constants for code replacement.
+     *
+     * @remarks
+     * Values are stringified and replaced in the source code during bundling.
+     * The `process.env.__PACKAGE_VERSION__` constant is automatically defined.
+     *
+     * @see {@link https://rsbuild.dev/config/source/define | Rsbuild define documentation}
+     *
+     * @defaultValue `{}`
+     */
     define: SourceConfig["define"];
-    /** Path to tsconfig for build (default: ./tsconfig.build.json) */
+    /**
+     * Path to the TypeScript configuration file for the build.
+     *
+     * @remarks
+     * If not specified, the plugin searches for `tsconfig.json` in the project root.
+     * A temporary tsconfig is generated for declaration generation regardless of this setting.
+     *
+     * @defaultValue `undefined` (auto-detected)
+     */
     tsconfigPath: string | undefined;
     /** Build targets to include (default: ["dev", "npm"]) */
     targets?: BuildTarget[];
@@ -1424,6 +1482,19 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     apiModel?: ApiModelOptions | boolean;
+    /**
+     * Whether to bundle JavaScript output into single files per entry point.
+     *
+     * @remarks
+     * - `true` (default): RSlib bundles JS into single files per entry (current behavior)
+     * - `false`: RSlib runs in bundleless mode, preserving file structure for JS output.
+     *   DTS is still bundled per entry via API Extractor (hybrid mode).
+     *   When `apiModel` is enabled with multiple entries, per-entry API models are
+     *   merged into a single `api.model.json` with multiple EntryPoint members.
+     *
+     * @defaultValue true
+     */
+    bundle?: boolean;
 }
 
 /**
@@ -1872,7 +1943,6 @@ export declare type PackageJson = JsonObject & PackageJson.NodeJsStandard & Pack
  *
  * - Consumes `entrypoints` map from AutoEntryPlugin
  * - Consumes `exportToOutputMap` for exportsAsIndexes mode
- * - Exposes `files-cache` for asset caching
  * - Consumes `use-rollup-types` flag from DtsPlugin
  *
  * @param options - Plugin configuration options
@@ -2846,6 +2916,16 @@ export declare class TsconfigResolver {
          * @defaultValue `true`
          */
         persistConfig?: boolean | PathLike;
+        /**
+         * Whether to run lint per entry point individually with per-entry logging.
+         *
+         * @remarks
+         * When enabled, each entry point is linted separately and results are
+         * logged per entry for better visibility in bundleless mode.
+         *
+         * @defaultValue false
+         */
+        perEntry?: boolean;
     }
 
     /**
@@ -3078,12 +3158,22 @@ export declare class TsconfigResolver {
 
     /**
      * Options for the VirtualEntryPlugin.
+     *
+     * @remarks
+     * Virtual entries are used for special files that need bundling but should not
+     * generate type declarations or appear in package.json exports. Common use cases
+     * include pnpmfile.cjs or other configuration files.
+     *
      * @public
      */
     export declare interface VirtualEntryPluginOptions {
         /**
-         * Set of virtual entry names (without extensions).
-         * Used by DtsPlugin to skip type generation for these entries.
+         * Set of virtual entry names (without file extensions).
+         *
+         * @remarks
+         * These names are exposed to DtsPlugin to skip type generation.
+         * For example, if `virtualEntryNames` contains `"pnpmfile"`, the
+         * entry `pnpmfile.cjs` will be bundled but no `pnpmfile.d.ts` will be generated.
          */
         virtualEntryNames: Set<string>;
     }