@savvy-web/rspress-builder 1.0.29 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ npm install --save-dev @savvy-web/rspress-builder
 pnpm add -D @savvy-web/rspress-builder
 ```
 
-`@rspress/core`, `react`, `react-dom` and `@tsdown/css` are peer dependencies the host plugin provides.
+`@rspress/core`, `react`, `react-dom` and `typescript` are peer dependencies the host plugin provides. `@tsdown/css` is a regular dependency of this package, so you do not install it yourself — tsdown loads it lazily when a CSS file is encountered.
 
 ## Quick start
 
@@ -29,7 +29,7 @@ await build();
 Pass options to tune the preset — for example, to bundle `@rspress/core` declarations into the output types or disable the runtime bundle for a plugin with no browser component:
 
 ```ts
-await build({ dtsBundledPackages: ["@rspress/core"] });
+await build({ bundledPackages: ["@rspress/core"] });
 await build({ runtime: false });
 ```
 
@@ -52,12 +52,27 @@ For advanced use, `definePlugin` and `runBuild` remain exported as primitives.
 
 `definePlugin` keeps a small surface because RSPress plugins have a fixed shape:
 
-- `runtime` — build the `./runtime` bundle. `true` (default) builds it, `false` disables it for a plugin with no runtime, an object tunes its externals. It does not probe the filesystem; pass `false` when there is no runtime entry.
-- `plugin` — externals tuning for the plugin (`.`) bundle.
-- `dtsBundledPackages` — packages whose declarations are inlined into the bundled `.d.ts`, for example `["@rspress/core"]`.
-- `apiModel` — API Extractor api-model generation, on by default. Pass `false` to opt out.
+- `runtime` — build the `./runtime` bundle. `true` (default) builds it, `false` disables it for a plugin with no runtime, an object tunes its dependency posture (`externals`, `bundledPackages`, `dtsExternals`, `bundleNodeModules`). It does not probe the filesystem; pass `false` when there is no runtime entry.
+- `plugin` — dependency posture tuning for the plugin (`.`) bundle; same shape as `runtime`'s object form.
+- `externals` — build-wide externals merged into both bundles' built-in lists.
+- `bundledPackages` — packages whose declarations are inlined into the bundled `.d.ts`, for example `["@rspress/core"]`.
+- `dtsExternals` — packages externalized in the dts pass only (referenced via `import` in the emitted `.d.ts`) while the JS pass still bundles them.
+- `bundleNodeModules` — force-bundle node_modules (and workspace) JS dependencies into the package output.
+- `meta` — API Extractor api-model generation, on by default. Pass `false` to opt out.
 - `transform`, `jsx`, `define` — forwarded to the underlying bundler config.
 
+`bundledPackages`, `dtsExternals` and `bundleNodeModules` can be set build-wide and/or tuned per bundle via `plugin`/`runtime`; a per-bundle value wins over the build-wide one. `externals` is the exception — a build-wide value merges into BOTH bundles rather than being overridden.
+
+## Ambient environment types
+
+`@savvy-web/rspress-builder` ships a `./env` types-only export with the ambient declarations an RSPress runtime component needs: `import.meta.env` (Vite's build-mode env, `SSG_MD`/`SSR`/`MODE`/`BASE_URL`/`PROD`/`DEV`) plus `*.css` and `*.module.css` module declarations. Add a triple-slash reference to a `.d.ts` in your project to pull them in:
+
+```ts
+/// <reference types="@savvy-web/rspress-builder/env" />
+```
+
+`@savvy-web/bundler` ships the same pattern for its own build-injected key — see [its README](https://www.npmjs.com/package/@savvy-web/bundler#readme) — via `/// <reference types="@savvy-web/bundler/env" />`, which gives you `process.env.__PACKAGE_VERSION__`.
+
 ## License
 
 [MIT](LICENSE)

package/ecma.json

@@ -1,8 +1,9 @@
 {
+	"//": "types and lib REPLACE the base list rather than merging with it. If you override either, re-list every entry you still need, including node.",
 	"$schema": "https://json.schemastore.org/tsconfig.json",
 	"compilerOptions": {
 		"allowSyntheticDefaultImports": true,
-		"composite": true,
+		"composite": false,
 		"declaration": true,
 		"declarationDir": "${configDir}/dist",
 		"declarationMap": false,
@@ -42,7 +43,8 @@
 		"${configDir}/__fixtures__/**/*"
 	],
 	"include": [
-		"${configDir}/types/*.ts",
+		"${configDir}/src/*.d.ts",
+		"${configDir}/types/*.d.ts",
 		"${configDir}/package.json",
 		"${configDir}/*.ts",
 		"${configDir}/*.cts",

package/env.d.ts

@@ -0,0 +1,114 @@
+// Ambient module + import.meta.env declarations for RSPress plugin runtimes built with
+// @savvy-web/rspress-builder. Replaces the rslib-era @rslib/core/types reference.
+
+type CSSModuleClasses = Readonly<Record<string, string>>;
+
+declare module "*.module.css" {
+	const classes: CSSModuleClasses;
+	export default classes;
+}
+declare module "*.css" {}
+
+/**
+ * The `ImportMetaEnv` interface defines the shape of the `import.meta.env` object, which contains environment variables
+ * injected by Vite during the build process. These variables provide information about the build environment,
+ * such as whether the app is running in development or production mode, whether it is being server-side rendered, and other relevant details.
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
+ */
+interface ImportMetaEnv {
+	/**
+	 * Environment variable so React components can distinguish SSG-MD (markdown)
+	 * rendering from browser rendering and customize their output
+	 * @example
+	 * ```typescript
+	 * export function Tab({ label }: { label: string }) {
+	 *     if (import.meta.env.SSG_MD) {
+	 *         // This will be returned as a static string in the markdown output
+	 *         return <>{`** Here is a Tab named ${label}**`}</>;
+	 *     }
+	 *     // This will be returned as a React component in the browser
+	 *     return <div class="tab">{label}</div>;
+	 * }
+	 * ```
+	 * @see {@link https://rspress.rs/guide/basic/ssg-md|RSPress | SSG-MD }
+	 * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
+	 * */
+
+	readonly SSG_MD: boolean;
+	/**
+	 * whether the Vite app is running in SSR (server-side rendering) mode. Allows you to
+	 * conditionally render React components differently for SSR vs. browser rendering.
+	 *
+	 * @example
+	 * ```typescript
+	 * export function DebugInfo() {
+	 *     if (import.meta.env.SSR) {
+	 *         return <div class="debug-info">Debug info here</div>;
+	 *     }
+	 *     return null;
+	 * }
+	 * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
+	 */
+	readonly SSR: boolean;
+
+	/**
+	 * Environment variable so React components can distinguish between development and
+	 * production builds
+	 *
+	 *  @example
+	 *  ```typescript
+	 *  export function DebugInfo() {
+	 *      if (import.meta.env.MODE === "development") {
+	 *          return <div class="debug-info">Debug info here</div>;
+	 *      }
+	 *      return null;
+	 *  }
+	 *  ```
+	 * @see {@link https://vite.dev/guide/env-and-mode#modes|Vite | Modes }
+	 */
+	readonly MODE: "development" | "production";
+
+	/**
+	 * Base public path when served in development or production. Valid values include:
+	 * Absolute URL pathname, e.g. `/foo/`
+	 *   - Full URL, e.g. `https://bar.com/foo/` (The origin part won't be used in development so the value is the same as /foo/)
+	 *   - Empty string or `./` (for embedded deployment)
+	 * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
+	 */
+	readonly BASE_URL: string;
+
+	/**
+	 * whether the Vite app is running in production mode:
+	 *   - running the dev server with `NODE_ENV='production'`
+	 *   - running an app built with `NODE_ENV='production'`)
+	 *
+	 *  Always the opposite of `import.meta.env.DEV`
+	 *
+	 * @see {@link https://vite.dev/guide/env-and-mode#env-files|Vite | Modes }
+	 */
+	readonly PROD: boolean;
+
+	/**
+	 * whether the Vite app is running in development mode:
+	 *   - running the dev server with `NODE_ENV='development'`
+	 *   - running an app built with `NODE_ENV='development'`
+	 *
+	 *  Always the opposite of `import.meta.env.PROD`.
+	 * @see {@link https://vite.dev/guide/env-and-mode#env-files|Vite | Modes }
+	 */
+	readonly DEV: boolean;
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: ImportMeta is used by TypeScript but may appear unused to the linter
+interface ImportMeta {
+	/**
+	 * The `import.meta` object contains metadata about the current module. It is a standard
+	 * feature in JavaScript modules. The `env` property on `import.meta` is a custom property injected
+	 * by Vite that provides access to environment variables defined in the Vite configuration or `.env` files.
+	 * RSPress uses this to provide information about the build environment, such as whether the app is running
+	 * in development or production mode, whether it is being server-side rendered, and other relevant environment details.
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta|}
+	 * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
+	 */
+	env: ImportMetaEnv;
+}

package/index.d.ts

@@ -1,13 +1,21 @@
-import { BuildConfig, BuildConfigInput, RunOptions, runBuild } from "@savvy-web/bundler";
+import { BuildConfig, BuildConfigInput, BuildEntryOverride, RunOptions, runBuild } from "@savvy-web/bundler";
 //#region src/index.d.ts
 /**
- * Per-bundle externals tuning for a single partition (plugin or runtime).
+ * Per-bundle dependency posture for a single partition (plugin or runtime). Mirrors the
+ * bundler's `BuildEntryOverride`; a value set here wins over the build-wide option of the
+ * same name.
  *
  * @public
  */
 interface RspressBundleOptions {
-  /** Additional externals merged with the built-ins for that bundle. */
+  /** Additional externals merged with this bundle's built-ins and the build-wide `externals`. */
   readonly externals?: ReadonlyArray<string>;
+  /** Packages whose declarations are inlined into this bundle's dts. */
+  readonly bundledPackages?: ReadonlyArray<string> | undefined;
+  /** Packages externalized in this bundle's dts pass only, referenced via import in the emitted `.d.ts`. */
+  readonly dtsExternals?: ReadonlyArray<string> | undefined;
+  /** Force-bundle node_modules JS dependencies into this bundle's output. */
+  readonly bundleNodeModules?: boolean | undefined;
 }
 /**
  * Options for `definePlugin`. Deliberately small — RSPress plugins have a fixed shape.
@@ -23,10 +31,20 @@ interface RspressPluginOptions {
   readonly runtime?: boolean | RspressBundleOptions;
   /** Tuning for the plugin (`.`) bundle (node, bundled). */
   readonly plugin?: RspressBundleOptions;
+  /** Build-wide externals merged into BOTH bundles' built-in lists. */
+  readonly externals?: ReadonlyArray<string>;
   /** Packages whose declarations are inlined into the bundled dts (e.g. [`@rspress/core`]). */
-  readonly dtsBundledPackages?: ReadonlyArray<string>;
+  readonly bundledPackages?: ReadonlyArray<string> | undefined;
+  /**
+   * Packages externalized in the dts pass ONLY — referenced via `import` in the emitted
+   * `.d.ts` rather than inlined — while the JS pass still bundles them. Declare these as
+   * package dependencies so consumers can resolve the emitted type imports.
+   */
+  readonly dtsExternals?: ReadonlyArray<string> | undefined;
+  /** Force-bundle node_modules (and workspace) JS dependencies into the package output. */
+  readonly bundleNodeModules?: boolean | undefined;
   /** API-model generation. Defaults to on (documents plugin options AND runtime components). `false` opts out. */
-  readonly apiModel?: BuildConfigInput["meta"];
+  readonly meta?: BuildConfigInput["meta"];
   /** Final package.json mutation; defaults to the bundler's defaultManifestTransform. */
   readonly transform?: BuildConfigInput["transform"];
   /** JSX override; defaults to tsconfig-inferred. */
@@ -56,5 +74,5 @@ declare function definePlugin(options?: RspressPluginOptions): BuildConfig;
  */
 declare function build(options?: RspressPluginOptions, overrides?: Partial<RunOptions>): Promise<void>;
 //#endregion
-export { RspressBundleOptions, RspressPluginOptions, type RunOptions, build, definePlugin, runBuild };
+export { type BuildConfig, type BuildConfigInput, type BuildEntryOverride, RspressBundleOptions, RspressPluginOptions, type RunOptions, build, definePlugin, runBuild };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -24,7 +24,13 @@ function definePlugin(options = {}) {
 	const runtimeEnabled = runtimeOpt !== false;
 	const runtimeTuning = typeof runtimeOpt === "object" ? runtimeOpt : {};
 	const pluginTuning = options.plugin ?? {};
-	const pluginExternals = [...PLUGIN_EXTERNALS, ...pluginTuning.externals ?? []];
+	const dedupe = (xs) => [...new Set(xs)];
+	const sharedExternals = options.externals ?? [];
+	const pluginExternals = dedupe([
+		...PLUGIN_EXTERNALS,
+		...sharedExternals,
+		...pluginTuning.externals ?? []
+	]);
 	const overrides = runtimeEnabled ? [{
 		entries: ["./runtime"],
 		outSubdir: "runtime",
@@ -36,16 +42,29 @@ function definePlugin(options = {}) {
 			},
 			inject: true
 		},
-		externals: [...RUNTIME_EXTERNALS, ...runtimeTuning.externals ?? []]
+		externals: dedupe([
+			...RUNTIME_EXTERNALS,
+			...sharedExternals,
+			...runtimeTuning.externals ?? []
+		]),
+		...(runtimeTuning.bundledPackages ?? options.bundledPackages) !== void 0 ? { bundledPackages: runtimeTuning.bundledPackages ?? options.bundledPackages } : {},
+		...(runtimeTuning.dtsExternals ?? options.dtsExternals) !== void 0 ? { dtsExternals: runtimeTuning.dtsExternals ?? options.dtsExternals } : {},
+		...(runtimeTuning.bundleNodeModules ?? options.bundleNodeModules) !== void 0 ? { bundleNodeModules: runtimeTuning.bundleNodeModules ?? options.bundleNodeModules } : {}
 	}] : [];
+	const define = {
+		"import.meta.env": "import.meta.env",
+		...options.define
+	};
+	const bundledPackages = pluginTuning.bundledPackages ?? options.bundledPackages;
+	const dtsExternals = pluginTuning.dtsExternals ?? options.dtsExternals;
+	const bundleNodeModules = pluginTuning.bundleNodeModules ?? options.bundleNodeModules;
 	return defineBuild({
 		externals: pluginExternals,
-		define: {
-			"import.meta.env": "import.meta.env",
-			...options.define
-		},
-		...options.dtsBundledPackages !== void 0 ? { bundledPackages: options.dtsBundledPackages } : {},
-		...options.apiModel !== void 0 ? { meta: options.apiModel } : {},
+		define,
+		...bundledPackages !== void 0 ? { bundledPackages } : {},
+		...dtsExternals !== void 0 ? { dtsExternals } : {},
+		...bundleNodeModules !== void 0 ? { bundleNodeModules } : {},
+		...options.meta !== void 0 ? { meta: options.meta } : {},
 		...options.transform !== void 0 ? { transform: options.transform } : {},
 		...options.jsx !== void 0 ? { jsx: options.jsx } : {},
 		...overrides.length > 0 ? { overrides } : {}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rspress-builder",
-	"version": "1.0.29",
+	"version": "1.1.0",
 	"private": false,
 	"description": "RSPress plugin builder for the Silk Suite, built on @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/rspress-builder",
@@ -25,15 +25,16 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
-		"./rspress-env.d.ts": "./rspress-env.d.ts",
+		"./env": {
+			"types": "./env.d.ts"
+		},
 		"./tsconfig/ecma.json": "./ecma.json",
 		"./tsconfig/plugin.json": "./tsconfig/plugin.json",
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/bundler": "2.0.12",
-		"@savvy-web/tsdown-plugins": "2.2.1",
-		"@tsdown/css": "^0.22.12"
+		"@savvy-web/bundler": "2.1.0",
+		"@tsdown/css": "^0.22.14"
 	},
 	"peerDependencies": {
 		"@rspress/core": "^2.0.0",

package/tsconfig/plugin.json

@@ -1,11 +1,65 @@
 {
-	"$schema": "https://json.schemastore.org/tsconfig",
+	"//": "types and lib REPLACE the base list rather than merging with it. If you override either, re-list every entry you still need, including node.",
+	"$schema": "https://json.schemastore.org/tsconfig.json",
 	"compilerOptions": {
+		"allowSyntheticDefaultImports": true,
+		"composite": false,
+		"declaration": true,
+		"declarationDir": "${configDir}/dist",
+		"declarationMap": false,
+		"emitDeclarationOnly": false,
+		"esModuleInterop": true,
+		"exactOptionalPropertyTypes": true,
+		"explainFiles": false,
+		"forceConsistentCasingInFileNames": true,
+		"incremental": true,
+		"isolatedDeclarations": false,
+		"isolatedModules": true,
 		"jsx": "react-jsx",
 		"lib": ["es2025", "dom"],
-		"types": ["node", "react", "react-dom"]
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"outDir": "${configDir}/dist",
+		"resolveJsonModule": true,
+		"rootDir": "${configDir}",
+		"skipLibCheck": true,
+		"sourceMap": false,
+		"strict": true,
+		"strictNullChecks": true,
+		"target": "es2025",
+		"tsBuildInfoFile": "${configDir}/dist/.tsbuildinfo.lib",
+		"typeRoots": ["${configDir}/node_modules/@types", "${configDir}/types"],
+		"types": ["node", "react", "react-dom"],
+		"verbatimModuleSyntax": true
 	},
-	"exclude": ["${configDir}/node_modules", "${configDir}/dist"],
-	"extends": "../ecma.json",
-	"include": ["${configDir}/types/*.d.ts", "${configDir}/src/**/*.ts", "${configDir}/src/**/*.tsx"]
+	"exclude": [
+		"${configDir}/node_modules",
+		"${configDir}/dist/**/*",
+		"${configDir}/__test__/fixtures/*.ts",
+		"${configDir}/__test__/fixtures/*.tsx",
+		"${configDir}/__test__/fixtures/*.cts",
+		"${configDir}/__test__/fixtures/*.mts",
+		"${configDir}/__test__/**/fixtures/**/*",
+		"${configDir}/__fixtures__/**/*"
+	],
+	"include": [
+		"${configDir}/types/*.d.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"
+	]
 }

package/rspress-env.d.ts

@@ -1,19 +0,0 @@
-// Ambient module + import.meta.env declarations for RSPress plugin runtimes built with
-// @savvy-web/rspress-builder. Replaces the rslib-era @rslib/core/types reference.
-
-type CSSModuleClasses = Readonly<Record<string, string>>;
-
-declare module "*.module.css" {
-	const classes: CSSModuleClasses;
-	export default classes;
-}
-declare module "*.css" {}
-
-interface ImportMetaEnv {
-	readonly [key: string]: string | boolean | undefined;
-	/** RSPress static-site-generation markdown flag, resolved per site build. */
-	readonly SSG_MD?: boolean;
-}
-interface ImportMeta {
-	readonly env: ImportMetaEnv;
-}