@savvy-web/rslib-builder 0.13.0 → 0.14.0

package/README.md

@@ -4,39 +4,22 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen)](https://nodejs.org)
 
-Build modern ESM Node.js libraries with minimal configuration. Handles
-TypeScript declarations, package.json transformations, and PNPM workspace
-resolution automatically.
+Build modern ESM Node.js libraries with minimal configuration. Handles TypeScript declarations, package.json transformations, and PNPM workspace resolution automatically.
 
 ## Features
 
-- **Zero-Config Entry Detection** - Auto-discovers
-  entry points from package.json exports
-- **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
-- **Flexible Formats** - ESM, CJS, or dual format
-  output with per-entry format overrides
-- **TSDoc Validation** - Pre-build documentation
-  validation with automatic public API discovery
+- **Zero-Config Entry Detection** - Auto-discovers entry points from package.json exports
+- **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
+- **Flexible Formats** - ESM, CJS, or dual format output with per-entry format overrides
+- **TSDoc Validation** - Pre-build documentation validation with automatic public API discovery
 
 ## Installation
 
 ```bash
-npm install --save-dev \
-  @savvy-web/rslib-builder \
-  @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

package/index.d.ts

@@ -421,6 +421,13 @@ export declare interface DtsPluginOptions {
      * The API model is excluded from npm publish (not added to `files` array).
      */
     apiModel?: ApiModelOptions | boolean;
+    /**
+     * Path prefix for emitted DTS files.
+     * Used in dual format builds to place declarations in format subdirectories
+     * (e.g., `esm/index.d.ts`, `cjs/index.d.cts`).
+     * Metadata files (api.json, tsdoc-metadata.json, tsconfig.json) are NOT prefixed.
+     */
+    dtsPathPrefix?: string;
 }
 
 /**
@@ -647,6 +654,14 @@ export declare interface FilesArrayPluginOptions<TTarget extends string = string
      * Passed to the `transformFiles` callback to allow target-specific transformations.
      */
     target: TTarget;
+    /**
+     * Format directories to include in the files array.
+     * Used in dual format builds so npm's `files` field includes
+     * format directories (e.g., `["esm", "cjs"]`).
+     * Directory names are treated as recursive includes by npm,
+     * so individual files under these dirs are filtered out.
+     */
+    formatDirs?: string[];
 }
 
 /**
@@ -1164,6 +1179,7 @@ export declare class NodeLibraryBuilder {
         externals: never[];
         apiModel: true;
         bundle: true;
+        cjsInterop: false;
     };
     /**
      * Merges user-provided options with default options.
@@ -1528,6 +1544,15 @@ export declare interface NodeLibraryBuilderOptions {
      * @defaultValue true
      */
     bundle?: boolean;
+    /**
+     * Enable CJS default export interop for CommonJS output files.
+     * When true, CJS files are patched so `require('module')` returns
+     * the default export directly instead of `{ default: value }`.
+     * Named exports are preserved as properties on the default value.
+     * Only affects CJS format output; ESM is unchanged.
+     * @defaultValue false
+     */
+    cjsInterop?: boolean;
 }
 
 /**

package/index.js

@@ -1502,14 +1502,15 @@ function runTsgo(options) {
                             let outputPath = file.relativePath;
                             if (outputPath.startsWith("src/")) outputPath = outputPath.slice(4);
                             if (".d.ts" !== dtsExtension && outputPath.endsWith(".d.ts")) outputPath = outputPath.replace(/\.d\.ts$/, dtsExtension);
-                            const jsOutputPath = outputPath.replace(/\.d\.(ts|mts|cts)$/, ".js");
+                            const prefixedPath = options.dtsPathPrefix ? `${options.dtsPathPrefix}/${outputPath}` : outputPath;
+                            const jsOutputPath = prefixedPath.replace(/\.d\.(ts|mts|cts)$/, ".js");
                             if (!context.compilation.assets[jsOutputPath]) continue;
                             let content = await readFile(file.path, "utf-8");
                             content = stripSourceMapComment(content);
-                            const source = new context.sources.OriginalSource(content, outputPath);
-                            context.compilation.emitAsset(outputPath, source);
+                            const source = new context.sources.OriginalSource(content, prefixedPath);
+                            context.compilation.emitAsset(prefixedPath, source);
                             emittedCount++;
-                            if (filesArray && outputPath.endsWith(".d.ts")) filesArray.add(outputPath);
+                            if (filesArray && prefixedPath.endsWith(".d.ts")) filesArray.add(prefixedPath);
                         }
                         core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted ${emittedCount} declaration file${1 === emittedCount ? "" : "s"} through asset pipeline`);
                     }
@@ -1597,12 +1598,13 @@ function runTsgo(options) {
                                 let emittedCount = 0;
                                 for (const [entryName, tempBundledPath] of bundledFiles){
                                     const bundledFileName = `${entryName}${bundledDtsExtension}`;
+                                    const prefixedBundledFileName = options.dtsPathPrefix ? `${options.dtsPathPrefix}/${bundledFileName}` : bundledFileName;
                                     let content = await readFile(tempBundledPath, "utf-8");
                                     content = stripSourceMapComment(content);
-                                    const source = new context.sources.OriginalSource(content, bundledFileName);
-                                    context.compilation.emitAsset(bundledFileName, source);
+                                    const source = new context.sources.OriginalSource(content, prefixedBundledFileName);
+                                    context.compilation.emitAsset(prefixedBundledFileName, source);
                                     emittedCount++;
-                                    if (filesArray) filesArray.add(bundledFileName);
+                                    if (filesArray) filesArray.add(prefixedBundledFileName);
                                 }
                                 core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted ${emittedCount} bundled declaration file${1 === emittedCount ? "" : "s"} through asset pipeline`);
                             }
@@ -1624,7 +1626,7 @@ function runTsgo(options) {
                                         hasTsdocMetadata: !!tsdocMetadataPath,
                                         hasTsconfig: !!state.parsedConfig && !!state.tsconfigPath,
                                         cwd,
-                                        distPath: `dist/${envId}`
+                                        distPath: `dist/${options.buildTarget ?? envId}`
                                     });
                                 }
                             }
@@ -1654,14 +1656,16 @@ function runTsgo(options) {
                             }
                             if (options.bundle) for (const [entryName] of bundledFiles){
                                 const bundledFileName = `${entryName}${bundledDtsExtension}`;
-                                const mapFileName = `${bundledFileName}.map`;
+                                const prefixedBundledFileName = options.dtsPathPrefix ? `${options.dtsPathPrefix}/${bundledFileName}` : bundledFileName;
+                                const mapFileName = `${prefixedBundledFileName}.map`;
                                 for (const file of dtsFiles){
                                     if (file.relativePath.endsWith(".d.ts.map")) continue;
                                     let outputPath = file.relativePath;
                                     if (outputPath.startsWith("src/")) outputPath = outputPath.slice(4);
                                     if (".d.ts" !== dtsExtension && outputPath.endsWith(".d.ts")) outputPath = outputPath.replace(/\.d\.ts$/, dtsExtension);
-                                    const mapFileName = `${outputPath}.map`;
-                                    if (context.compilation.assets[mapFileName]) delete context.compilation.assets[mapFileName];
+                                    const prefixedOutputPath = options.dtsPathPrefix ? `${options.dtsPathPrefix}/${outputPath}` : outputPath;
+                                    const individualMapFileName = `${prefixedOutputPath}.map`;
+                                    if (context.compilation.assets[individualMapFileName]) delete context.compilation.assets[individualMapFileName];
                                 }
                                 if (context.compilation.assets[mapFileName]) delete context.compilation.assets[mapFileName];
                             }
@@ -1830,6 +1834,7 @@ const FilesArrayPlugin = (options)=>({
                 const license = await TextAsset.create(context, "LICENSE", false);
                 if (license) filesArray.add(license.fileName);
                 for (const assetName of Object.keys(context.compilation.assets))if (!assetName.endsWith(".map") && !filesArray.has(assetName)) filesArray.add(assetName);
+                if (options?.formatDirs) for (const dir of options.formatDirs)filesArray.add(dir);
                 if (options?.transformFiles) await options.transformFiles({
                     compilation: context.compilation,
                     filesArray,
@@ -1848,6 +1853,11 @@ const FilesArrayPlugin = (options)=>({
                         ...previousFiles,
                         ...Array.from(filesArray)
                     ].sort());
+                    if (options?.formatDirs) {
+                        for (const file of [
+                            ...allFiles
+                        ])if (options.formatDirs.some((dir)=>file.startsWith(`${dir}/`))) allFiles.delete(file);
+                    }
                     if (0 === allFiles.size) delete packageJson.data.files;
                     else {
                         const newFiles = new Set([
@@ -2678,6 +2688,20 @@ const VirtualEntryPlugin = (options)=>{
         }
     };
 };
+const CJS_INTEROP_FOOTER = `
+if (module.exports && module.exports.__esModule && 'default' in module.exports) {
+  var _def = module.exports.default;
+  if (_def !== null && _def !== undefined && (typeof _def === 'object' || typeof _def === 'function')) {
+    var _keys = Object.keys(module.exports);
+    for (var _i = 0; _i < _keys.length; _i++) {
+      var _key = _keys[_i];
+      if (_key !== 'default' && _key !== '__esModule' && !(_key in _def)) {
+        _def[_key] = module.exports[_key];
+      }
+    }
+  }
+  module.exports = _def;
+}`;
 /* v8 ignore next -- @preserve */ class NodeLibraryBuilder {
     static VALID_TARGETS = [
         "dev",
@@ -2694,7 +2718,8 @@ const VirtualEntryPlugin = (options)=>{
         ],
         externals: [],
         apiModel: true,
-        bundle: true
+        bundle: true,
+        cjsInterop: false
     };
     static mergeOptions(options = {}) {
         const copyPatterns = [
@@ -2715,6 +2740,7 @@ const VirtualEntryPlugin = (options)=>{
             externals: options.externals ?? NodeLibraryBuilder.DEFAULT_OPTIONS.externals,
             apiModel: options.apiModel ?? NodeLibraryBuilder.DEFAULT_OPTIONS.apiModel,
             bundle: options.bundle ?? NodeLibraryBuilder.DEFAULT_OPTIONS.bundle,
+            cjsInterop: options.cjsInterop ?? NodeLibraryBuilder.DEFAULT_OPTIONS.cjsInterop,
             ...void 0 !== options.entry && {
                 entry: options.entry
             },
@@ -2794,7 +2820,6 @@ const VirtualEntryPlugin = (options)=>{
         const hasFormatOverrides = void 0 !== entryFormats && Object.keys(entryFormats).length > 0;
         const collapseIndex = bundle || !(options.exportsAsIndexes ?? false);
         const baseOutputDir = `dist/${target}`;
-        const outputDir = isDualFormat ? `${baseOutputDir}/${primaryFormat}` : baseOutputDir;
         const apiModelForTarget = "npm" === target ? options.apiModel : void 0;
         const sourceMap = "dev" === target;
         const externalsConfig = options.externals && options.externals.length > 0 ? {
@@ -2843,6 +2868,9 @@ const VirtualEntryPlugin = (options)=>{
             target,
             ...options.transformFiles && {
                 transformFiles: options.transformFiles
+            },
+            ...isDualFormat && {
+                formatDirs: formats
             }
         }));
         plugins.push(...options.plugins);
@@ -2859,11 +2887,14 @@ const VirtualEntryPlugin = (options)=>{
             format: primaryFormat,
             ...void 0 !== apiModelForTarget && {
                 apiModel: apiModelForTarget
+            },
+            ...isDualFormat && {
+                dtsPathPrefix: primaryFormat
             }
         }));
         const lib = {
             id: isDualFormat ? `${target}-${primaryFormat}` : target,
-            outBase: bundle ? outputDir : "src",
+            outBase: bundle ? baseOutputDir : "src",
             output: {
                 target: "node",
                 module: true,
@@ -2871,7 +2902,10 @@ const VirtualEntryPlugin = (options)=>{
                 sourceMap,
                 ...bundlelessOutput,
                 distPath: {
-                    root: outputDir
+                    root: baseOutputDir,
+                    ...isDualFormat && {
+                        js: primaryFormat
+                    }
                 },
                 copy: {
                     patterns: options.copyPatterns
@@ -2892,6 +2926,11 @@ const VirtualEntryPlugin = (options)=>{
                     entry
                 },
                 define: sourceDefine
+            },
+            ...options.cjsInterop && "cjs" === primaryFormat && {
+                footer: {
+                    js: CJS_INTEROP_FOOTER
+                }
             }
         };
         const hasRegularEntries = void 0 !== options.entry || NodeLibraryBuilder.packageHasExports();
@@ -2902,11 +2941,17 @@ const VirtualEntryPlugin = (options)=>{
         if (hasRegularEntries) {
             libConfigs.push(lib);
             if (isDualFormat) for (const secondaryFormat of formats.slice(1)){
-                const secondaryOutputDir = `${baseOutputDir}/${secondaryFormat}`;
                 const secondaryPlugins = [
-                    FilesArrayPlugin({
-                        target
-                    }),
+                    {
+                        name: "strip-metadata-assets",
+                        setup (api) {
+                            api.processAssets({
+                                stage: "additional"
+                            }, (context)=>{
+                                for (const name of Object.keys(context.compilation.assets))if ("package.json" === name || "README.md" === name || "LICENSE" === name) delete context.compilation.assets[name];
+                            });
+                        }
+                    },
                     DtsPlugin({
                         ...options.tsconfigPath && {
                             tsconfigPath: options.tsconfigPath
@@ -2917,19 +2962,21 @@ const VirtualEntryPlugin = (options)=>{
                             bundledPackages: options.dtsBundledPackages
                         },
                         buildTarget: target,
-                        format: secondaryFormat
+                        format: secondaryFormat,
+                        dtsPathPrefix: secondaryFormat
                     })
                 ];
                 const secondaryLib = {
                     id: `${target}-${secondaryFormat}`,
-                    outBase: bundle ? secondaryOutputDir : "src",
+                    outBase: bundle ? baseOutputDir : "src",
                     output: {
                         target: "node",
                         cleanDistPath: false,
                         sourceMap,
                         ...bundlelessOutput,
                         distPath: {
-                            root: secondaryOutputDir
+                            root: baseOutputDir,
+                            js: secondaryFormat
                         },
                         ...externalsConfig
                     },
@@ -2947,6 +2994,11 @@ const VirtualEntryPlugin = (options)=>{
                             entry
                         },
                         define: sourceDefine
+                    },
+                    ...options.cjsInterop && "cjs" === secondaryFormat && {
+                        footer: {
+                            js: CJS_INTEROP_FOOTER
+                        }
                     }
                 };
                 libConfigs.push(secondaryLib);
@@ -3012,6 +3064,11 @@ const VirtualEntryPlugin = (options)=>{
                                 tsconfigPath: options.tsconfigPath
                             },
                             define: sourceDefine
+                        },
+                        ...options.cjsInterop && "cjs" === overrideFormat && {
+                            footer: {
+                                js: CJS_INTEROP_FOOTER
+                            }
                         }
                     };
                     libConfigs.push(overrideLib);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rslib-builder",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"private": false,
 	"description": "RSlib-based build system for Node.js libraries with automatic package.json transformation, TypeScript declaration bundling, and multi-target support",
 	"keywords": [
@@ -25,7 +25,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/savvy-web/rslib-builder.git"
+		"url": "git+https://github.com/savvy-web/rslib-builder.git"
 	},
 	"license": "MIT",
 	"author": {