@savvy-web/rslib-builder 0.18.2 → 0.19.0

package/README.md

@@ -12,6 +12,7 @@ Build modern ESM Node.js libraries with minimal configuration. Handles TypeScrip
 - **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
+- **RSPress Plugin Builder** - Dedicated builder for RSPress plugins with dual-bundle architecture (plugin + runtime) and React support
 - **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
@@ -35,13 +36,33 @@ export default NodeLibraryBuilder.create({
 
 Build with `rslib build --env-mode dev` or `rslib build --env-mode npm`.
 
+## RSPress Plugins
+
+Build RSPress plugins with zero-config dual-bundle output (plugin + runtime):
+
+```typescript
+// rslib.config.ts
+import { RSPressPluginBuilder } from '@savvy-web/rslib-builder';
+
+export default RSPressPluginBuilder.create({
+  plugin: {
+    externals: ['typescript', 'shiki'],
+  },
+  runtime: {
+    externals: ['@rspress/plugin-llms'],
+  },
+});
+```
+
+RSPressPluginBuilder auto-detects the runtime entry at `src/runtime/index.tsx`, handles React JSX compilation, CSS modules, and built-in RSPress externals. For advanced configuration, see [RSPress Plugin Setup](../docs/guides/rspress-plugins.md).
+
 ## Documentation
 
-For configuration options, API reference, and advanced usage, see [docs](./docs/).
+For configuration options, API reference, and advanced usage, see [docs](../docs/).
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 

package/index.d.ts

@@ -53,6 +53,7 @@ import type { RslibConfig } from '@rslib/core';
 import { ScriptTarget } from 'typescript';
 import type { SourceConfig } from '@rsbuild/core';
 import ts from 'typescript';
+import type { TSConfigJsonWithSchema } from '../types/tsconfig-json.js';
 
 /**
  * Options for API model generation.
@@ -454,6 +455,18 @@ export declare interface DtsPluginOptions {
      * Metadata files (api.json, tsdoc-metadata.json, tsconfig.json) are NOT prefixed.
      */
     dtsPathPrefix?: string;
+    /** Override the default LibraryTSConfigFile used for temp tsconfig generation. */
+    tsconfigPreset?: LibraryTSConfigFile;
+    /**
+     * Explicitly provide entry points instead of discovering from package.json exports.
+     * Map of entry name to source path (e.g., `{ index: "./src/index.ts" }`).
+     *
+     * @remarks
+     * Used by RSPressPluginBuilder to prevent cross-contamination between the plugin lib
+     * and runtime lib — each lib's DtsPlugin only processes its own entries.
+     * When set, the EntryExtractor is bypassed entirely.
+     */
+    overrideEntries?: Record<string, string>;
 }
 
 /**
@@ -1115,6 +1128,38 @@ export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
  */
 export declare type LibraryFormat = "esm" | "cjs";
 
+/**
+ * Represents a TypeScript configuration file for library builds.
+ *
+ * @remarks
+ * This class extends {@link TSConfigFile} to add library-specific build methods for
+ * generating bundled build configurations. It provides methods to:
+ * - Generate build-mode specific configurations
+ * - Write temporary configuration files for build tools
+ * - Transform paths and filter includes based on build mode
+ *
+ * @see {@link TSConfigFile} for the base class
+ * @internal
+ */
+export declare class LibraryTSConfigFile extends TSConfigFile {
+    /**
+     * Write the bundle-mode configuration to a temporary file.
+     *
+     * @remarks
+     * Creates a temporary tsconfig.json file with absolute paths that work from /tmp.
+     * Uses the base compiler options from the template but generates include patterns
+     * dynamically based on the actual package structure.
+     *
+     * The temporary file will be automatically cleaned up when the process exits.
+     *
+     * @param mode - Build mode (dev, npm)
+     * @returns Absolute path to the temporary file
+     */
+    writeBundleTempConfig(_mode: "dev" | "npm", options?: {
+        types?: string[];
+    }): string;
+}
+
 /**
  * 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.
@@ -2356,6 +2401,95 @@ export declare function resolvePublishTargets(packageJson: PackageJson, cwd: str
  */
 export declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
 
+/** Built-in externals for RSPress plugin bundles. */
+export declare const RSPRESS_PLUGIN_EXTERNALS: readonly string[];
+
+/** Built-in externals for RSPress runtime bundles. */
+export declare const RSPRESS_RUNTIME_EXTERNALS: readonly string[];
+
+/**
+ * Builder for RSPress plugin packages with dual-bundle architecture.
+ *
+ * @remarks
+ * Produces up to two RSlib lib configs:
+ * - **Plugin lib**: The main RSPress plugin entry (always generated)
+ * - **Runtime lib**: React components for the RSPress theme (auto-detected or explicit)
+ *
+ * @public
+ */
+export declare class RSPressPluginBuilder {
+    private static readonly VALID_MODES;
+    /**
+     * Merges user-provided options with defaults.
+     *
+     * @param options - Partial configuration options to merge
+     * @returns Merged options with defaults applied
+     */
+    static mergeOptions(options?: Partial<RSPressPluginBuilderOptions>): RSPressPluginBuilderOptions;
+    /**
+     * Creates an async RSLib configuration function for RSPress plugin packages.
+     *
+     * @param options - Configuration options for the builder
+     * @returns An async function compatible with RSLib's config system
+     */
+    static create(options?: Partial<RSPressPluginBuilderOptions>): RslibConfigAsyncFn;
+    /**
+     * Creates a single-mode build configuration with plugin and optional runtime libs.
+     *
+     * @param mode - The build mode ("dev" or "npm")
+     * @param options - Configuration options
+     * @returns Promise resolving to the RSLib configuration
+     */
+    static createSingleMode(mode: BuildMode, options: RSPressPluginBuilderOptions): Promise<RslibConfig>;
+    /**
+     * Determines whether the runtime bundle should be enabled.
+     */
+    private static shouldEnableRuntime;
+    /**
+     * Creates the plugin lib configuration.
+     */
+    private static createPluginLib;
+    private static createRuntimeLib;
+}
+
+/**
+ * Options for RSPressPluginBuilder.
+ * @public
+ */
+export declare interface RSPressPluginBuilderOptions {
+    /** Plugin bundle configuration. Always generated. */
+    plugin?: RSPressPluginBundleOptions;
+    /** Runtime bundle configuration. Auto-detected from `src/runtime/index.tsx`, or `false` to disable. */
+    runtime?: RSPressPluginBundleOptions | false;
+    /** API model generation options. Default: `true`. */
+    apiModel?: ApiModelOptions | boolean;
+    /** Packages to bundle in TypeScript declarations. */
+    dtsBundledPackages?: string[];
+    /** Custom package.json transform function. */
+    transform?: TransformPackageJsonFn;
+    /** Path to custom tsconfig.json. Overrides the default RSPress plugin preset. */
+    tsconfigPath?: string;
+    /** Build modes to produce. Default: `["dev", "npm"]`. */
+    modes?: BuildMode[];
+    /** Static files to copy to output (e.g., i18n JSON). */
+    copyPatterns?: (string | CopyPatternConfig)[];
+}
+
+/**
+ * Options for an individual RSPress plugin bundle (plugin or runtime).
+ * @public
+ */
+export declare interface RSPressPluginBundleOptions {
+    /** Entry point path. Plugin default: `"./src/index.ts"`, runtime default: `"./src/runtime/index.tsx"` */
+    entry?: string;
+    /** Additional externals merged with built-in RSPress externals. */
+    externals?: (string | RegExp)[];
+    /** Additional Rsbuild plugins. `pluginReact()` is auto-added on runtime. */
+    plugins?: RsbuildPlugin[];
+    /** Additional define constants merged with `{ "import.meta.env": "import.meta.env" }`. */
+    define?: SourceConfig["define"];
+}
+
 /**
  * Function to transform package.json during the build process.
  *
@@ -2393,6 +2527,103 @@ export declare type TransformPackageJsonFn = (context: {
     pkg: PackageJson;
 }) => PackageJson;
 
+/**
+ * Represents a TypeScript configuration file with utilities for path resolution.
+ *
+ * @remarks
+ * This class provides convenient access to TypeScript configuration files,
+ * with automatic path resolution and JSON parsing. It implements custom
+ * inspection for improved debugging output in Node.js console.
+ *
+ * The class handles workspace-aware path resolution that correctly handles
+ * cross-package references by using node_modules symlinks when crossing
+ * package boundaries.
+ *
+ * The class uses lazy getters for both path resolution and configuration
+ * parsing, ensuring that file I/O only occurs when these properties are
+ * accessed. This makes it efficient to create instances without immediately
+ * reading from disk.
+ *
+ * This base class is suitable for workspace-level configurations. For library
+ * build configurations that require bundle transformations, use
+ * {@link LibraryTSConfigFile}.
+ *
+ * @see {@link LibraryTSConfigFile} for library build configurations
+ * @internal
+ */
+export declare class TSConfigFile {
+    pathname: string;
+    /**
+     * Human-readable description of what this configuration is used for.
+     *
+     * @remarks
+     * This description helps developers understand the purpose and intended use
+     * case for this particular TypeScript configuration.
+     */
+    readonly description: string;
+    /**
+     * Relative path from current working directory to the config file.
+     *
+     * @remarks
+     * Returns a relative path string prefixed with `./` that points from the
+     * current working directory to the TypeScript configuration file. This is
+     * useful for displaying user-friendly paths in logs and error messages.
+     *
+     * The path is computed lazily each time it's accessed, so it will reflect
+     * changes if the current working directory changes during execution.
+     *
+     * @returns A relative path string with `./` prefix (e.g., `./tsconfig/ecma/lib.json`)
+     */
+    get path(): string;
+    /**
+     * Get configuration with `$\{configDir\}` variables replaced.
+     *
+     * @remarks
+     * Returns the configuration with all `${configDir}` template variables replaced
+     * with the relative path to the package root. This is useful for configurations
+     * that use template variables for path resolution.
+     *
+     * @returns The configuration with transformed paths
+     */
+    get bundled(): TSConfigJsonWithSchema;
+    /**
+     * Parsed TypeScript configuration object.
+     *
+     * @remarks
+     * Returns the TypeScript configuration object imported at build time.
+     * The configuration object includes standard TypeScript compiler options
+     * and other tsconfig.json fields with JSON schema validation.
+     *
+     * @returns The parsed TypeScript configuration as a {@link TSConfigJsonWithSchema} object
+     *
+     * @throws If the configuration file is not found in imports
+     *
+     * @see {@link TSConfigJsonWithSchema} for the configuration type definition
+     */
+    get config(): TSConfigJsonWithSchema;
+    /**
+     * Creates a new TSConfigFile instance.
+     *
+     * @remarks
+     * Initializes a TSConfigFile with the specified description and absolute path
+     * to a TypeScript configuration file. The constructor sets up lazy getters for
+     * the `path` and `config` properties using `Object.defineProperty`, making
+     * them enumerable but computed on demand.
+     *
+     * Additionally, it configures custom Node.js inspection behavior via
+     * `util.inspect.custom` to provide pretty-printed output when the
+     * instance is logged to the console. This includes showing all nested
+     * levels, colors, and unlimited array lengths for better debugging.
+     *
+     * No file I/O occurs during construction - files are only read when
+     * the `config` getter is accessed.
+     *
+     * @param description - Human-readable description of what this configuration is used for
+     * @param pathname - Absolute path to the TypeScript configuration file
+     */
+    constructor(description: string, pathname: string);
+}
+
 /**
  * Resolves TypeScript ParsedCommandLine to a JSON-serializable tsconfig format.
  *

package/index.js

@@ -494,11 +494,21 @@ const AutoEntryPlugin = (options)=>{
     };
 };
 var lib_namespaceObject = JSON.parse('{"$schema":"https://json.schemastore.org/tsconfig.json","compilerOptions":{"allowSyntheticDefaultImports":true,"composite":true,"declaration":true,"declarationDir":"${configDir}/dist","declarationMap":false,"emitDeclarationOnly":false,"esModuleInterop":true,"explainFiles":false,"forceConsistentCasingInFileNames":true,"incremental":true,"isolatedDeclarations":false,"isolatedModules":true,"exactOptionalPropertyTypes":true,"jsx":"preserve","lib":["esnext"],"module":"nodenext","moduleResolution":"nodenext","outDir":"${configDir}/dist","resolveJsonModule":true,"rootDir":"${configDir}","skipLibCheck":true,"sourceMap":false,"strict":true,"strictNullChecks":true,"target":"es2023","tsBuildInfoFile":"${configDir}/dist/.tsbuildinfo.lib","typeRoots":["${configDir}/node_modules/@types","${configDir}/types"],"verbatimModuleSyntax":true},"exclude":["${configDir}/node_modules","${configDir}/dist/**/*"],"include":["${configDir}/types/*.ts","${configDir}/package.json","${configDir}/*.ts","${configDir}/*.cts","${configDir}/*.mts","${configDir}/src/**/*.ts","${configDir}/src/**/*.tsx","${configDir}/src/**/*.cts","${configDir}/src/**/*.mts","${configDir}/lib/**/*.ts","${configDir}/lib/**/*.tsx","${configDir}/lib/**/*.cts","${configDir}/lib/**/*.mts","${configDir}/__test__/**/*.ts","${configDir}/__test__/**/*.tsx","${configDir}/__test__/**/*.cts","${configDir}/__test__/**/*.mts","${configDir}/public/**/*.json"]}');
+var plugin_namespaceObject = JSON.parse('{"$schema":"https://json.schemastore.org/tsconfig.json","compilerOptions":{"composite":true,"declaration":true,"exactOptionalPropertyTypes":true,"jsx":"react-jsx","module":"esnext","moduleResolution":"bundler","resolveJsonModule":true,"skipLibCheck":true,"strict":true,"strictNullChecks":true,"target":"es2023"},"exclude":["${configDir}/node_modules","${configDir}/dist","${configDir}/.rslib"],"include":["${configDir}/src/**/*.ts","${configDir}/src/**/*.tsx","${configDir}/src/**/*.mts","${configDir}/src/**/*.cts","${configDir}/src/**/*.mdx","${configDir}/types/**/*.ts"]}');
+var website_namespaceObject = JSON.parse('{"$schema":"https://json.schemastore.org/tsconfig.json","compilerOptions":{"exactOptionalPropertyTypes":true,"jsx":"react-jsx","lib":["DOM","ES2023"],"module":"esnext","moduleResolution":"bundler","resolveJsonModule":true,"skipLibCheck":true,"strict":true,"strictNullChecks":true,"target":"es2023"},"exclude":["${configDir}/node_modules","${configDir}/dist","${configDir}/.rspress","${configDir}/.rslib"],"include":["${configDir}/*.ts","${configDir}/*.mts","${configDir}/*.cts","${configDir}/**/*.tsx","${configDir}/docs/**/*.mdx"]}');
 const requireCJS = createRequire(import.meta.url);
 const jsonImports = new Map([
     [
         join(import.meta.dirname, "../public/tsconfig/ecma/lib.json"),
         lib_namespaceObject
+    ],
+    [
+        join(import.meta.dirname, "../public/tsconfig/rspress/plugin.json"),
+        plugin_namespaceObject
+    ],
+    [
+        join(import.meta.dirname, "../public/tsconfig/rspress/website.json"),
+        website_namespaceObject
     ]
 ]);
 function transformStringsDeep(value, transform) {
@@ -593,11 +603,17 @@ class LibraryTSConfigFile extends TSConfigFile {
     }
 }
 const NodeEcmaLib = new LibraryTSConfigFile("ECMAScript library build configuration", join(import.meta.dirname, "../public/tsconfig/ecma/lib.json"));
+const RSPressPlugin = new LibraryTSConfigFile("RSPress plugin build configuration", join(import.meta.dirname, "../public/tsconfig/rspress/plugin.json"));
+const RSPressWebsite = new TSConfigFile("RSPress website configuration", join(import.meta.dirname, "../public/tsconfig/rspress/website.json"));
 const TSConfigs = {
     node: {
         ecma: {
             lib: NodeEcmaLib
         }
+    },
+    rspress: {
+        plugin: RSPressPlugin,
+        website: RSPressWebsite
     }
 };
 function compileRule(rule) {
@@ -1185,9 +1201,9 @@ async function bundleDtsFiles(options) {
             }
         }
         const dtsExtension = "cjs" === options.format ? ".d.cts" : ".d.ts";
+        const isMainEntry = "index" === entryName || 1 === entryPoints.size;
         const outputFileName = `${entryName}${dtsExtension}`;
         const tempBundledPath = join(tempOutputDir, outputFileName);
-        const isMainEntry = "index" === entryName || 1 === entryPoints.size;
         const generateApiModel = apiModelEnabled;
         const tempApiModelPath = generateApiModel ? join(tempOutputDir, `${entryName}.api.json`) : void 0;
         const generateTsdocMetadata = tsdocMetadataEnabled && isMainEntry;
@@ -1465,7 +1481,8 @@ function runTsgo(options) {
                             process.chdir(cwd);
                             const projectConfigPath = findTsConfig(cwd);
                             const projectTypes = projectConfigPath ? loadTsConfig(projectConfigPath).options.types : void 0;
-                            configTsconfigPath = TSConfigs.node.ecma.lib.writeBundleTempConfig(options.buildMode, projectTypes ? {
+                            const preset = options.tsconfigPreset ?? TSConfigs.node.ecma.lib;
+                            configTsconfigPath = preset.writeBundleTempConfig(options.buildMode, projectTypes ? {
                                 types: projectTypes
                             } : void 0);
                         } finally{
@@ -1573,28 +1590,34 @@ function runTsgo(options) {
                             const packageJsonContent = await readFile(packageJsonPath, "utf-8");
                             packageJson = JSON.parse(packageJsonContent);
                         }
-                        const { entries, exportPaths } = new EntryExtractor().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;
-                            if (!resolvedSourcePath.startsWith(cwd)) {
-                                log.global.info(`Skipping export "${entryName}" (source outside package: ${sourcePath})`);
-                                continue;
-                            }
-                            let finalSourcePath = sourcePath;
-                            if (apiExtractorMapping && resolvedSourcePath === apiExtractorMapping.tempPath) {
-                                finalSourcePath = apiExtractorMapping.originalPath;
-                                log.global.info(`Using original path for api-extractor: ${finalSourcePath}`);
+                        let exportPaths = {};
+                        if (options.overrideEntries) for (const [entryName, sourcePath] of Object.entries(options.overrideEntries))entryPoints.set(entryName, sourcePath);
+                        else {
+                            const extracted = new EntryExtractor().extract(packageJson);
+                            const entries = extracted.entries;
+                            exportPaths = extracted.exportPaths;
+                            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;
+                                if (!resolvedSourcePath.startsWith(cwd)) {
+                                    log.global.info(`Skipping export "${entryName}" (source outside package: ${sourcePath})`);
+                                    continue;
+                                }
+                                let finalSourcePath = sourcePath;
+                                if (apiExtractorMapping && resolvedSourcePath === apiExtractorMapping.tempPath) {
+                                    finalSourcePath = apiExtractorMapping.originalPath;
+                                    log.global.info(`Using original path for api-extractor: ${finalSourcePath}`);
+                                }
+                                entryPoints.set(entryName, finalSourcePath);
                             }
-                            entryPoints.set(entryName, finalSourcePath);
                         }
                         if (0 === entryPoints.size) log.global.warn("No TypeScript exports found in package.json, skipping declaration bundling");
                         else {
@@ -3341,4 +3364,281 @@ function resolvePublishTargets(packageJson, cwd, outdir) {
         };
     });
 }
-export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, PublishTargetPlugin, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, VirtualEntryPlugin, resolvePublishTargets };
+const RSPRESS_PLUGIN_EXTERNALS = [
+    "@rspress/core"
+];
+const RSPRESS_RUNTIME_EXTERNALS = [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "@rspress/core",
+    "@theme"
+];
+const DEFAULT_RUNTIME_ENTRY = "./src/runtime/index.tsx";
+/* v8 ignore next -- @preserve */ class RSPressPluginBuilder {
+    static VALID_MODES = [
+        "dev",
+        "npm"
+    ];
+    static mergeOptions(options = {}) {
+        return {
+            ...void 0 !== options.plugin && {
+                plugin: options.plugin
+            },
+            ...void 0 !== options.runtime && {
+                runtime: options.runtime
+            },
+            apiModel: options.apiModel ?? true,
+            modes: options.modes ?? [
+                "dev",
+                "npm"
+            ],
+            copyPatterns: options.copyPatterns ?? [],
+            ...void 0 !== options.dtsBundledPackages && {
+                dtsBundledPackages: options.dtsBundledPackages
+            },
+            ...void 0 !== options.transform && {
+                transform: options.transform
+            },
+            ...void 0 !== options.tsconfigPath && {
+                tsconfigPath: options.tsconfigPath
+            }
+        };
+    }
+    static create(options = {}) {
+        const mergedOptions = RSPressPluginBuilder.mergeOptions(options);
+        return async ({ envMode })=>{
+            const mode = envMode || "dev";
+            const validModes = mergedOptions.modes ?? RSPressPluginBuilder.VALID_MODES;
+            if (!validModes.includes(mode)) throw new Error(`Invalid env-mode: "${mode}". Must be one of: ${validModes.join(", ")}\nExample: rslib build --env-mode npm`);
+            return RSPressPluginBuilder.createSingleMode(mode, mergedOptions);
+        };
+    }
+    static async createSingleMode(mode, options) {
+        const cwd = process.cwd();
+        const packageJsonPath = join(cwd, "package.json");
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        const runtimeEnabled = RSPressPluginBuilder.shouldEnableRuntime(options, cwd);
+        const baseOutputDir = `dist/${mode}`;
+        const publishTargets = "npm" === mode ? resolvePublishTargets(packageJson, cwd, external_node_path_resolve(cwd, baseOutputDir)) : [];
+        const hasTargets = publishTargets.length > 0;
+        const libConfigs = [];
+        libConfigs.push(RSPressPluginBuilder.createPluginLib(mode, options, hasTargets, publishTargets));
+        if (runtimeEnabled) {
+            const runtimeOpts = "object" == typeof options.runtime ? options.runtime : {};
+            const runtimeLib = await RSPressPluginBuilder.createRuntimeLib(mode, runtimeOpts, options);
+            libConfigs.push(runtimeLib);
+        }
+        return defineConfig({
+            lib: libConfigs,
+            ...options.tsconfigPath && {
+                source: {
+                    tsconfigPath: options.tsconfigPath
+                }
+            },
+            performance: {
+                buildCache: {
+                    cacheDirectory: `.rslib/cache/${mode}`
+                }
+            }
+        });
+    }
+    static shouldEnableRuntime(options, cwd) {
+        if (false === options.runtime) return false;
+        if ("object" == typeof options.runtime) return true;
+        return existsSync(join(cwd, "src/runtime/index.tsx"));
+    }
+    static createPluginLib(mode, options, hasTargets, publishTargets) {
+        const pluginOpts = options.plugin ?? {};
+        const sourceMap = "dev" === mode;
+        const baseOutputDir = `dist/${mode}`;
+        const plugins = [];
+        const apiModelConfig = "object" == typeof options.apiModel ? options.apiModel : {};
+        const tsdocConfig = apiModelConfig.tsdoc;
+        const lintConfig = tsdocConfig?.lint;
+        const lintEnabled = false !== options.apiModel && false !== lintConfig;
+        if (lintEnabled) {
+            const { lint: _lint, ...tsdocWithoutLint } = tsdocConfig ?? {};
+            const lintOptions = {
+                ...tsdocConfig && Object.keys(tsdocWithoutLint).length > 0 && {
+                    tsdoc: tsdocWithoutLint
+                },
+                ..."object" == typeof lintConfig ? lintConfig : {}
+            };
+            plugins.push(TsDocLintPlugin(lintOptions));
+        }
+        const userTransform = options.transform;
+        const transformFn = !hasTargets && userTransform ? (pkg)=>userTransform({
+                mode,
+                target: void 0,
+                pkg
+            }) : void 0;
+        plugins.push(PackageJsonTransformPlugin({
+            forcePrivate: "dev" === mode,
+            bundle: false,
+            mode,
+            format: "esm",
+            ...transformFn && {
+                transform: transformFn
+            }
+        }));
+        plugins.push(FilesArrayPlugin({
+            mode
+        }));
+        plugins.push(DtsPlugin({
+            ...options.tsconfigPath ? {
+                tsconfigPath: options.tsconfigPath
+            } : {
+                tsconfigPreset: TSConfigs.rspress.plugin
+            },
+            abortOnError: true,
+            bundle: true,
+            ...options.dtsBundledPackages && {
+                bundledPackages: options.dtsBundledPackages
+            },
+            buildMode: mode,
+            format: "esm",
+            ...void 0 !== options.apiModel && {
+                apiModel: options.apiModel
+            },
+            overrideEntries: {
+                index: pluginOpts.entry ?? "./src/index.ts"
+            }
+        }));
+        if (pluginOpts.plugins) plugins.push(...pluginOpts.plugins);
+        if (hasTargets) {
+            const cwd = process.cwd();
+            plugins.push(PublishTargetPlugin({
+                targets: publishTargets,
+                stagingDir: external_node_path_resolve(cwd, baseOutputDir),
+                mode,
+                ...userTransform && {
+                    transform: userTransform
+                }
+            }));
+        }
+        const externals = [
+            ...RSPRESS_PLUGIN_EXTERNALS,
+            ...pluginOpts.externals ?? []
+        ];
+        const sourceDefine = {
+            "import.meta.env": "import.meta.env",
+            ...pluginOpts.define
+        };
+        return {
+            id: `${mode}-plugin`,
+            output: {
+                target: "node",
+                module: true,
+                cleanDistPath: true,
+                sourceMap,
+                distPath: {
+                    root: baseOutputDir
+                },
+                copy: {
+                    patterns: options.copyPatterns ?? []
+                },
+                externals
+            },
+            format: "esm",
+            bundle: true,
+            experiments: {
+                advancedEsm: true
+            },
+            plugins,
+            source: {
+                ...options.tsconfigPath && {
+                    tsconfigPath: options.tsconfigPath
+                },
+                entry: {
+                    index: pluginOpts.entry ?? "./src/index.ts"
+                },
+                define: sourceDefine
+            }
+        };
+    }
+    static async createRuntimeLib(mode, runtimeOpts, options) {
+        let pluginReact;
+        try {
+            const reactPlugin = await import("@rsbuild/plugin-react");
+            pluginReact = reactPlugin.pluginReact;
+        } catch (err) {
+            const code = err.code;
+            if ("MODULE_NOT_FOUND" === code || "ERR_MODULE_NOT_FOUND" === code) throw new Error("@rsbuild/plugin-react is required for RSPress runtime bundles. Install it as a dev dependency: pnpm add -D @rsbuild/plugin-react");
+            throw err;
+        }
+        const sourceMap = "dev" === mode;
+        const runtimeOutputDir = `dist/${mode}/runtime`;
+        const plugins = [];
+        plugins.push(DtsPlugin({
+            ...options.tsconfigPath ? {
+                tsconfigPath: options.tsconfigPath
+            } : {
+                tsconfigPreset: TSConfigs.rspress.plugin
+            },
+            abortOnError: true,
+            bundle: true,
+            ...options.dtsBundledPackages && {
+                bundledPackages: options.dtsBundledPackages
+            },
+            buildMode: mode,
+            format: "esm",
+            apiModel: false,
+            overrideEntries: {
+                index: runtimeOpts.entry ?? DEFAULT_RUNTIME_ENTRY
+            }
+        }));
+        plugins.push(pluginReact());
+        if (runtimeOpts.plugins) plugins.push(...runtimeOpts.plugins);
+        const externals = [
+            ...RSPRESS_RUNTIME_EXTERNALS,
+            ...runtimeOpts.externals ?? []
+        ];
+        const sourceDefine = {
+            "import.meta.env": "import.meta.env",
+            ...runtimeOpts.define
+        };
+        return {
+            id: `${mode}-runtime`,
+            output: {
+                target: "web",
+                cleanDistPath: false,
+                sourceMap,
+                distPath: {
+                    root: runtimeOutputDir
+                },
+                externals,
+                cssModules: {
+                    namedExport: false,
+                    exportLocalsConvention: "camelCaseOnly"
+                }
+            },
+            format: "esm",
+            bundle: true,
+            experiments: {
+                advancedEsm: true
+            },
+            plugins,
+            source: {
+                ...options.tsconfigPath && {
+                    tsconfigPath: options.tsconfigPath
+                },
+                entry: {
+                    index: runtimeOpts.entry ?? DEFAULT_RUNTIME_ENTRY
+                },
+                define: sourceDefine
+            },
+            tools: {
+                rspack (config, { rspack }) {
+                    config.plugins ??= [];
+                    config.plugins.push(new rspack.BannerPlugin({
+                        banner: 'import "./index.css";',
+                        raw: true,
+                        include: /index\.js$/
+                    }));
+                }
+            }
+        };
+    }
+}
+export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, PublishTargetPlugin, RSPRESS_PLUGIN_EXTERNALS, RSPRESS_RUNTIME_EXTERNALS, RSPressPluginBuilder, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, VirtualEntryPlugin, resolvePublishTargets };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/rslib-builder",
-  "version": "0.18.2",
+  "version": "0.19.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,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/savvy-web/rslib-builder.git"
+    "url": "git+https://github.com/savvy-web/rslib-builder.git",
+    "directory": "package"
   },
   "license": "MIT",
   "author": {
@@ -40,7 +41,9 @@
       "import": "./index.js"
     },
     "./tsconfig/root.json": "./tsconfig/root.json",
-    "./tsconfig/ecma/lib.json": "./tsconfig/ecma/lib.json"
+    "./tsconfig/ecma/lib.json": "./tsconfig/ecma/lib.json",
+    "./tsconfig/rspress/plugin.json": "./tsconfig/rspress/plugin.json",
+    "./tsconfig/rspress/website.json": "./tsconfig/rspress/website.json"
   },
   "dependencies": {
     "@microsoft/tsdoc": "^0.16.0",
@@ -62,31 +65,44 @@
   },
   "peerDependencies": {
     "@microsoft/api-extractor": "^7.57.7",
+    "@rsbuild/plugin-react": "^1.4.0",
     "@rslib/core": "^0.20.0",
     "@types/node": "^25.2.0",
+    "@types/react": "^19.0.0",
     "@typescript/native-preview": "^7.0.0-dev.20260124.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {
     "@microsoft/api-extractor": {
       "optional": false
     },
+    "@rsbuild/plugin-react": {
+      "optional": true
+    },
     "@rslib/core": {
       "optional": false
     },
     "@types/node": {
       "optional": false
     },
+    "@types/react": {
+      "optional": true
+    },
     "@typescript/native-preview": {
       "optional": false
     },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
     "typescript": {
       "optional": false
     }
   },
-  "engines": {
-    "node": ">=24.0.0"
-  },
   "files": [
     "!rslib-builder.api.json",
     "!tsconfig.json",
@@ -98,6 +114,8 @@
     "package.json",
     "tsconfig/ecma/lib.json",
     "tsconfig/root.json",
+    "tsconfig/rspress/plugin.json",
+    "tsconfig/rspress/website.json",
     "tsdoc-metadata.json"
   ]
 }

package/tsconfig/rspress/plugin.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"compilerOptions": {
+		"composite": true,
+		"declaration": true,
+		"exactOptionalPropertyTypes": true,
+		"jsx": "react-jsx",
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"strictNullChecks": true,
+		"target": "es2023"
+	},
+	"exclude": ["${configDir}/node_modules", "${configDir}/dist", "${configDir}/.rslib"],
+	"include": [
+		"${configDir}/src/**/*.ts",
+		"${configDir}/src/**/*.tsx",
+		"${configDir}/src/**/*.mts",
+		"${configDir}/src/**/*.cts",
+		"${configDir}/src/**/*.mdx",
+		"${configDir}/types/**/*.ts"
+	]
+}

package/tsconfig/rspress/website.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"compilerOptions": {
+		"exactOptionalPropertyTypes": true,
+		"jsx": "react-jsx",
+		"lib": ["DOM", "ES2023"],
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"strictNullChecks": true,
+		"target": "es2023"
+	},
+	"exclude": ["${configDir}/node_modules", "${configDir}/dist", "${configDir}/.rspress", "${configDir}/.rslib"],
+	"include": [
+		"${configDir}/*.ts",
+		"${configDir}/*.mts",
+		"${configDir}/*.cts",
+		"${configDir}/**/*.tsx",
+		"${configDir}/docs/**/*.mdx"
+	]
+}