@savvy-web/rslib-builder 0.9.0 → 0.10.0

package/README.md

@@ -22,6 +22,10 @@ focus on your code.
   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

package/index.d.ts

@@ -395,6 +395,13 @@ export declare interface DtsPluginOptions {
      * Used to generate the correct temp tsconfig when tsconfigPath is not provided.
      */
     buildTarget?: "dev" | "npm";
+    /**
+     * Output format for the library.
+     * Affects the resolved tsconfig.json module settings:
+     * - `"esm"`: Uses ESNext module and Bundler resolution (default)
+     * - `"cjs"`: Uses CommonJS module and Node10 resolution
+     */
+    format?: "esm" | "cjs";
     /**
      * Options for API model generation.
      * When enabled, generates an `<unscopedPackageName>.api.json` file in the dist directory.
@@ -1055,6 +1062,17 @@ export declare type JsonPrimitive = string | number | boolean | null;
  */
 export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 
+/**
+ * Output format for library builds.
+ *
+ * @remarks
+ * - `"esm"` - ES Modules format (sets `type: "module"` in package.json)
+ * - `"cjs"` - CommonJS format (sets `type: "commonjs"` in package.json)
+ *
+ * @public
+ */
+export declare type LibraryFormat = "esm" | "cjs";
+
 /**
  * Allows creating a union type by combining primitive types and literal types
  * without sacrificing auto-completion in IDEs for the literal type part of the union.
@@ -1137,6 +1155,7 @@ export declare class NodeLibraryBuilder {
      * Arrays are deep-copied to prevent mutation of this object.
      */
     static readonly DEFAULT_OPTIONS: {
+        format: "esm";
         plugins: never[];
         define: {};
         copyPatterns: never[];
@@ -1179,12 +1198,65 @@ export declare class NodeLibraryBuilder {
      * @returns Promise resolving to the RSLib configuration
      */
     static createSingleTarget(target: BuildTarget, opts: NodeLibraryBuilderOptions): Promise<RslibConfig>;
+    /**
+     * Checks if the current package has exports defined in package.json.
+     * @internal
+     */
+    private static packageHasExports;
 }
 
 /**
  * @public
  */
 export declare interface NodeLibraryBuilderOptions {
+    /**
+     * Output format for main entry points.
+     * Also determines package.json `type` field:
+     * - `"esm"` → `"type": "module"`
+     * - `"cjs"` → `"type": "commonjs"`
+     *
+     * @defaultValue `"esm"`
+     */
+    format?: LibraryFormat;
+    /**
+     * Additional entry points bundled with custom output names.
+     * These entries bypass type generation and package.json exports
+     * but are included in the published package.
+     *
+     * @remarks
+     * Virtual entries are useful for special files like pnpm config files
+     * that need to be bundled but don't require type declarations or
+     * exposure as package exports.
+     *
+     * A module may have ONLY virtualEntries with no regular entry points.
+     *
+     * @example
+     * Mixed: regular entries + virtual entries
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   virtualEntries: {
+     *     "pnpmfile.cjs": {
+     *       source: "./src/pnpmfile.ts",
+     *       format: "cjs",
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     * Virtual-only: no regular entry points
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   format: "cjs",
+     *   virtualEntries: {
+     *     "pnpmfile.cjs": {
+     *       source: "./src/pnpmfile.ts",
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    virtualEntries?: Record<string, VirtualEntryConfig>;
     /** Override entry points (optional - will auto-detect from package.json) */
     entry?: Record<string, string | string[]>;
     /**
@@ -1848,6 +1920,15 @@ export declare const PackageJsonTransformPlugin: (options?: PackageJsonTransform
  * @public
  */
 export declare interface PackageJsonTransformPluginOptions {
+    /**
+     * Output format for the library.
+     * Determines the package.json `type` field:
+     * - `"esm"` → `"type": "module"`
+     * - `"cjs"` → `"type": "commonjs"`
+     *
+     * @defaultValue `"esm"`
+     */
+    format?: LibraryFormat;
     /**
      * Override the package name in the output package.json.
      *
@@ -2332,8 +2413,14 @@ export declare class TsconfigResolver {
      * - Excludes file selection (include, exclude, files, references)
      * - Adds $schema for IDE support
      *
+     * When `format` is `"cjs"`, the resolved config uses CommonJS-compatible settings:
+     * - `module: "commonjs"`
+     * - `moduleResolution: "node10"`
+     * - `esModuleInterop: true`
+     *
      * @param parsed - The parsed TypeScript configuration from `parseJsonConfigFileContent`
      * @param _rootDir - Reserved for future path normalization (currently unused)
+     * @param format - Optional output format to adjust module settings (`"esm"` or `"cjs"`)
      * @returns A JSON-serializable tsconfig object
      * @throws {@link TsconfigResolverError} If resolution fails for any option
          *
@@ -2353,7 +2440,7 @@ export declare class TsconfigResolver {
          *
          * @public
          */
-     resolve(parsed: ParsedCommandLine, _rootDir: string): ResolvedTsconfig;
+     resolve(parsed: ParsedCommandLine, _rootDir: string, format?: LibraryFormat): ResolvedTsconfig;
      /**
       * Adds converted enum options to the compiler options object.
       * @internal
@@ -2933,4 +3020,72 @@ export declare class TsconfigResolver {
      */
     export declare type TsDocTagGroup = "core" | "extended" | "discretionary";
 
+    /**
+     * Configuration for a virtual entry point.
+     *
+     * @remarks
+     * Virtual entries are bundled entry points that bypass type generation
+     * and package.json exports while still being included in the published package.
+     *
+     * @example
+     * ```typescript
+     * const config: VirtualEntryConfig = {
+     *   source: "./src/pnpmfile.ts",
+     *   format: "cjs",
+     * };
+     * ```
+     *
+     * @public
+     */
+    export declare interface VirtualEntryConfig {
+        /**
+         * Path to source file (relative to package root).
+         */
+        source: string;
+        /**
+         * Output format for this entry.
+         * If not specified, inherits from top-level `format` option.
+         */
+        format?: LibraryFormat;
+    }
+
+    /**
+     * Plugin to handle virtual entry points in RSlib builds.
+     *
+     * @remarks
+     * Virtual entries are special entry points that:
+     * - Are bundled like regular entries
+     * - Do NOT generate TypeScript declarations (.d.ts files)
+     * - Are NOT added to package.json exports
+     * - ARE added to package.json files array for publishing
+     *
+     * This plugin:
+     * 1. Exposes the virtual entry names for DtsPlugin to skip type generation
+     * 2. Adds virtual entry outputs to the files array in the additional stage
+     *
+     * @example
+     * ```typescript
+     * import { VirtualEntryPlugin } from '@savvy-web/rslib-builder';
+     *
+     * const plugin = VirtualEntryPlugin({
+     *   virtualEntryNames: new Set(['pnpmfile']),
+     * });
+     * ```
+     *
+     * @public
+     */
+    export declare const VirtualEntryPlugin: (options: VirtualEntryPluginOptions) => RsbuildPlugin;
+
+    /**
+     * Options for the VirtualEntryPlugin.
+     * @public
+     */
+    export declare interface VirtualEntryPluginOptions {
+        /**
+         * Set of virtual entry names (without extensions).
+         * Used by DtsPlugin to skip type generation for these entries.
+         */
+        virtualEntryNames: Set<string>;
+    }
+
     export { }

package/index.js

@@ -1,11 +1,11 @@
 /*! For license information please see index.js.LICENSE.txt */
-import { constants, existsSync, writeFileSync } from "node:fs";
+import { constants, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, relative, resolve as external_node_path_resolve } from "node:path";
 import { defineConfig } from "@rslib/core";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, unlink as promises_unlink, writeFile } from "node:fs/promises";
 import { logger as core_logger } from "@rsbuild/core";
 import picocolors from "picocolors";
-import { getWorkspaceRoot } from "workspace-tools";
+import { getWorkspaceManagerRoot } from "workspace-tools";
 import { spawn } from "node:child_process";
 import { StandardTags, Standardization, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
 import deep_equal from "deep-equal";
@@ -169,7 +169,7 @@ function getApiExtractorPath() {
     const cwd = process.cwd();
     const localApiExtractor = join(cwd, "node_modules", "@microsoft", "api-extractor");
     if (existsSync(localApiExtractor)) return localApiExtractor;
-    const workspaceRoot = getWorkspaceRoot(cwd);
+    const workspaceRoot = getWorkspaceManagerRoot(cwd);
     if (workspaceRoot) {
         const workspaceApiExtractor = join(workspaceRoot, "node_modules", "@microsoft", "api-extractor");
         if (existsSync(workspaceApiExtractor)) return workspaceApiExtractor;
@@ -679,7 +679,7 @@ class TsconfigResolver {
         const filename = lib.includes("/") || lib.includes("\\") ? lib.split(/[\\/]/).pop() ?? lib : lib;
         return filename.replace(/^lib\./, "").replace(/\.d\.ts$/, "");
     }
-    resolve(parsed, _rootDir) {
+    resolve(parsed, _rootDir, format) {
         const opts = parsed.options;
         const compilerOptions = {};
         this.addEnumOptions(compilerOptions, opts);
@@ -688,6 +688,11 @@ class TsconfigResolver {
         compilerOptions.noEmit = true;
         this.addPreservedBooleanOptions(compilerOptions, opts);
         this.addPreservedStringOptions(compilerOptions, opts);
+        if ("cjs" === format) {
+            compilerOptions.module = "commonjs";
+            compilerOptions.moduleResolution = "node10";
+            compilerOptions.esModuleInterop = true;
+        }
         return {
             $schema: TSCONFIG_SCHEMA_URL,
             compilerOptions
@@ -836,7 +841,7 @@ function getTsgoBinPath() {
     const cwd = process.cwd();
     const localTsgoBin = join(cwd, "node_modules", ".bin", "tsgo");
     if (existsSync(localTsgoBin)) return localTsgoBin;
-    const workspaceRoot = getWorkspaceRoot(cwd);
+    const workspaceRoot = getWorkspaceManagerRoot(cwd);
     if (workspaceRoot) {
         const workspaceTsgoBin = join(workspaceRoot, "node_modules", ".bin", "tsgo");
         if (existsSync(workspaceTsgoBin)) return workspaceTsgoBin;
@@ -1240,8 +1245,13 @@ function runTsgo(options) {
                         const extractor = new EntryExtractor();
                         const { entries } = extractor.extract(packageJson);
                         const entryPoints = new Map();
+                        const virtualEntryNames = api.useExposed("virtual-entry-names");
                         for (const [entryName, sourcePath] of Object.entries(entries)){
                             if (entryName.startsWith("bin/")) continue;
+                            if (virtualEntryNames?.has(entryName)) {
+                                log.global.info(`Skipping type generation for virtual entry: ${entryName}`);
+                                continue;
+                            }
                             if (!sourcePath.match(/\.(ts|mts|cts|tsx)$/)) continue;
                             if (sourcePath.includes(".test.") || sourcePath.includes("__test__")) continue;
                             const resolvedSourcePath = sourcePath.startsWith(".") ? join(cwd, sourcePath) : sourcePath;
@@ -1332,7 +1342,7 @@ function runTsgo(options) {
                             }
                             if (apiModelPath && state.parsedConfig && state.tsconfigPath) {
                                 const resolver = new TsconfigResolver();
-                                const resolvedTsconfig = resolver.resolve(state.parsedConfig, cwd);
+                                const resolvedTsconfig = resolver.resolve(state.parsedConfig, cwd, options.format);
                                 const tsconfigContent = `${JSON.stringify(resolvedTsconfig, null, "\t")}\n`;
                                 const tsconfigSource = new context.sources.OriginalSource(tsconfigContent, "tsconfig.json");
                                 context.compilation.emitAsset("tsconfig.json", tsconfigSource);
@@ -1578,7 +1588,7 @@ class PnpmCatalog {
     async getCatalog() {
         try {
             if (!this.cachedWorkspaceRoot) {
-                this.cachedWorkspaceRoot = getWorkspaceRoot(process.cwd());
+                this.cachedWorkspaceRoot = getWorkspaceManagerRoot(process.cwd());
                 if (!this.cachedWorkspaceRoot) throw new Error("Could not find workspace root - ensure you're in a workspace");
             }
             const workspaceFile = external_node_path_resolve(this.cachedWorkspaceRoot, "pnpm-workspace.yaml");
@@ -1864,6 +1874,7 @@ const PackageJsonTransformPlugin = (options = {})=>{
                 const processedPackageJson = await buildPackageJson(packageJson.data, isProduction, options.processTSExports, entrypoints, exportToOutputMap, options.bundle, options.transform);
                 packageJson.data = processedPackageJson;
                 if (options.forcePrivate) packageJson.data.private = true;
+                if (options.format) packageJson.data.type = "esm" === options.format ? "module" : "commonjs";
                 const useRollupTypes = api.useExposed("use-rollup-types");
                 if (useRollupTypes && packageJson.data.exports && "object" == typeof packageJson.data.exports) {
                     const exports = packageJson.data.exports;
@@ -2302,12 +2313,35 @@ const TsDocLintPlugin = (options = {})=>{
         }
     };
 };
+const VirtualEntryPlugin = (options)=>{
+    const { virtualEntryNames } = options;
+    return {
+        name: "virtual-entry-plugin",
+        setup (api) {
+            api.expose("virtual-entry-names", virtualEntryNames);
+            api.processAssets({
+                stage: "additional"
+            }, async (context)=>{
+                let filesArray = api.useExposed("files-array");
+                if (!filesArray) {
+                    filesArray = new Set();
+                    api.expose("files-array", filesArray);
+                }
+                for (const assetName of Object.keys(context.compilation.assets)){
+                    const baseName = assetName.replace(/\.(c|m)?js$/, "");
+                    if (virtualEntryNames.has(baseName)) filesArray.add(assetName);
+                }
+            });
+        }
+    };
+};
 /* v8 ignore next -- @preserve */ class NodeLibraryBuilder {
     static VALID_TARGETS = [
         "dev",
         "npm"
     ];
     static DEFAULT_OPTIONS = {
+        format: "esm",
         plugins: [],
         define: {},
         copyPatterns: [],
@@ -2332,6 +2366,7 @@ const TsDocLintPlugin = (options = {})=>{
             plugins: options.plugins ?? NodeLibraryBuilder.DEFAULT_OPTIONS.plugins,
             define: options.define ?? NodeLibraryBuilder.DEFAULT_OPTIONS.define,
             tsconfigPath: options.tsconfigPath,
+            format: options.format ?? NodeLibraryBuilder.DEFAULT_OPTIONS.format,
             targets: options.targets ?? NodeLibraryBuilder.DEFAULT_OPTIONS.targets,
             externals: options.externals ?? NodeLibraryBuilder.DEFAULT_OPTIONS.externals,
             apiModel: options.apiModel ?? NodeLibraryBuilder.DEFAULT_OPTIONS.apiModel,
@@ -2349,6 +2384,9 @@ const TsDocLintPlugin = (options = {})=>{
             },
             ...void 0 !== options.transform && {
                 transform: options.transform
+            },
+            ...void 0 !== options.virtualEntries && {
+                virtualEntries: options.virtualEntries
             }
         };
         return merged;
@@ -2387,10 +2425,12 @@ const TsDocLintPlugin = (options = {})=>{
                 target,
                 pkg
             }) : void 0;
+        const libraryFormat = options.format ?? "esm";
         plugins.push(PackageJsonTransformPlugin({
             forcePrivate: "dev" === target,
             bundle: true,
             target,
+            format: libraryFormat,
             ...transformFn && {
                 transform: transformFn
             }
@@ -2415,6 +2455,7 @@ const TsDocLintPlugin = (options = {})=>{
                 bundledPackages: options.dtsBundledPackages
             },
             buildTarget: target,
+            format: libraryFormat,
             ...void 0 !== apiModelForTarget && {
                 apiModel: apiModelForTarget
             }
@@ -2437,9 +2478,9 @@ const TsDocLintPlugin = (options = {})=>{
                     externals: options.externals
                 }
             },
-            format: "esm",
+            format: libraryFormat,
             experiments: {
-                advancedEsm: true
+                advancedEsm: "esm" === libraryFormat
             },
             bundle: true,
             plugins,
@@ -2456,10 +2497,70 @@ const TsDocLintPlugin = (options = {})=>{
                 }
             }
         };
+        const hasRegularEntries = void 0 !== options.entry || NodeLibraryBuilder.packageHasExports();
+        const virtualEntries = options.virtualEntries ?? {};
+        const hasVirtualEntries = Object.keys(virtualEntries).length > 0;
+        if (!hasRegularEntries && !hasVirtualEntries) throw new Error("No entry points configured. Provide package.json exports, explicit entry option, or virtualEntries.");
+        const libConfigs = [];
+        if (hasRegularEntries) libConfigs.push(lib);
+        if (hasVirtualEntries) {
+            const virtualByFormat = new Map();
+            for (const [outputName, config] of Object.entries(virtualEntries)){
+                const entryFormat = config.format ?? libraryFormat;
+                if (!virtualByFormat.has(entryFormat)) virtualByFormat.set(entryFormat, new Map());
+                const entryName = outputName.replace(/\.(c|m)?js$/, "");
+                const formatMap = virtualByFormat.get(entryFormat);
+                if (formatMap) formatMap.set(entryName, config.source);
+            }
+            for (const [format, entries] of virtualByFormat){
+                const virtualEntryNames = new Set(entries.keys());
+                const entryMap = Object.fromEntries(entries);
+                const virtualLib = {
+                    id: `${target}-virtual-${format}`,
+                    format,
+                    bundle: true,
+                    output: {
+                        target: "node",
+                        cleanDistPath: false,
+                        sourceMap: false,
+                        distPath: {
+                            root: outputDir
+                        },
+                        ...options.externals && options.externals.length > 0 && {
+                            externals: options.externals
+                        }
+                    },
+                    source: {
+                        entry: entryMap
+                    },
+                    plugins: [
+                        VirtualEntryPlugin({
+                            virtualEntryNames
+                        }),
+                        FilesArrayPlugin({
+                            target
+                        })
+                    ]
+                };
+                libConfigs.push(virtualLib);
+            }
+            if (hasRegularEntries) {
+                const allVirtualEntryNames = new Set();
+                for (const outputName of Object.keys(virtualEntries)){
+                    const entryName = outputName.replace(/\.(c|m)?js$/, "");
+                    allVirtualEntryNames.add(entryName);
+                }
+                plugins.push({
+                    name: "virtual-entry-names-exposer",
+                    setup (api) {
+                        api.expose("virtual-entry-names", allVirtualEntryNames);
+                    }
+                });
+                lib.plugins = plugins;
+            }
+        }
         return defineConfig({
-            lib: [
-                lib
-            ],
+            lib: libConfigs,
             ...options.tsconfigPath && {
                 source: {
                     tsconfigPath: options.tsconfigPath
@@ -2472,5 +2573,15 @@ const TsDocLintPlugin = (options = {})=>{
             }
         });
     }
+    static packageHasExports() {
+        try {
+            const packageJsonPath = join(process.cwd(), "package.json");
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+            const { exports } = packageJson;
+            return null != exports && "object" == typeof exports && Object.keys(exports).length > 0;
+        } catch  {
+            return false;
+        }
+    }
 }
-export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, extractEntriesFromPackageJson };
+export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, VirtualEntryPlugin, extractEntriesFromPackageJson };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rslib-builder",
-	"version": "0.9.0",
+	"version": "0.10.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": [
@@ -54,7 +54,7 @@
 		"picocolors": "^1.1.1",
 		"sort-package-json": "^3.6.1",
 		"tmp": "^0.2.5",
-		"workspace-tools": "^0.40.4",
+		"workspace-tools": "^0.41.0",
 		"yaml": "^2.8.2"
 	},
 	"peerDependencies": {