@savvy-web/rspress-builder 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @savvy-web/rspress-builder
+
+[![npm](https://img.shields.io/npm/v/@savvy-web%2Frspress-builder?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/rspress-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+
+Builds an [RSPress](https://rspress.rs/) plugin package on top of [`@savvy-web/bundler`](https://www.npmjs.com/package/@savvy-web/bundler). One `definePlugin` call produces the dual-bundle shape an RSPress plugin needs: a Node plugin entry plus a browser, bundleless, CSS-module React runtime entry, each with the right externals and platform already set.
+
+## Install
+
+```bash
+npm install --save-dev @savvy-web/rspress-builder
+# or
+pnpm add -D @savvy-web/rspress-builder
+```
+
+`@rspress/core`, `react`, `react-dom` and `@tsdown/css` are peer dependencies the host plugin provides.
+
+## Quick start
+
+Add a `savvy.build.ts` to the plugin package root. `definePlugin` returns a standard bundler config, which the re-exported `runBuild` consumes unchanged:
+
+```ts
+// savvy.build.ts
+import { definePlugin, runBuild } from "@savvy-web/rspress-builder";
+
+const config = definePlugin({ runtime: true, dtsBundledPackages: ["@rspress/core"] });
+
+export default config;
+
+if (import.meta.main) {
+  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
+}
+```
+
+Wire the build targets into `package.json` scripts and run them with Node's native TypeScript support:
+
+```json
+{
+  "scripts": {
+    "build:dev": "node savvy.build.ts --target dev",
+    "build:prod": "node savvy.build.ts --target prod"
+  }
+}
+```
+
+The plugin entry (`.`) builds for Node with `@rspress/core` externalized. The runtime entry (`./runtime`) builds for the browser, bundleless, with CSS modules enabled and React, `@rspress/core` and `@theme` externalized so RSPress provides them at site build time.
+
+## Configuration
+
+`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.
+- `transform`, `jsx`, `define` — forwarded to the underlying bundler config.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,43 @@
+import { BuildConfig, BuildConfigInput, RunOptions, runBuild } from "@savvy-web/bundler";
+
+//#region src/index.d.ts
+/** Per-bundle externals tuning for a single partition (plugin or runtime). */
+interface RspressBundleOptions {
+  /** Additional externals merged with the built-ins for that bundle. */
+  readonly externals?: ReadonlyArray<string>;
+}
+/** Options for {@link definePlugin}. Deliberately small — RSPress plugins have a fixed shape. */
+interface RspressPluginOptions {
+  /**
+   * Enable the `./runtime` bundle (browser, bundleless, CSS modules, React/@theme external).
+   * `true` (default) builds it; `false` disables it; an object tunes its externals.
+   * This does not auto-detect the filesystem — pass `false` for a plugin with no runtime.
+   */
+  readonly runtime?: boolean | RspressBundleOptions;
+  /** Tuning for the plugin (`.`) bundle (node, bundled). */
+  readonly plugin?: RspressBundleOptions;
+  /** Packages whose declarations are inlined into the bundled dts (e.g. ["@rspress/core"]). */
+  readonly dtsBundledPackages?: ReadonlyArray<string>;
+  /** API-model generation. Defaults to on (documents plugin options AND runtime components). `false` opts out. */
+  readonly apiModel?: BuildConfigInput["meta"];
+  /** Final package.json mutation; defaults to the bundler's defaultManifestTransform. */
+  readonly transform?: BuildConfigInput["transform"];
+  /** JSX override; defaults to tsconfig-inferred. */
+  readonly jsx?: BuildConfigInput["jsx"];
+  /**
+   * Build-wide compile-time global replacements forwarded to every partition (the bundler's
+   * `define` is build-wide; there is no per-bundle define). Merged AFTER the `import.meta.env`
+   * identity map, so a user key may override it intentionally. Values are inserted verbatim
+   * (string literals must be quoted).
+   */
+  readonly define?: Record<string, string>;
+}
+/**
+ * Build an RSPress plugin package: a Node plugin entry (`.`) plus a browser, bundleless,
+ * CSS-module React runtime entry (`./runtime`). Returns a standard {@link BuildConfig};
+ * hand it to {@link runBuild} from a self-executing `savvy.build.ts`.
+ */
+declare function definePlugin(options?: RspressPluginOptions): BuildConfig;
+//#endregion
+export { RspressBundleOptions, RspressPluginOptions, type RunOptions, definePlugin, runBuild };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,53 @@
+import { defineBuild, runBuild } from "@savvy-web/bundler";
+
+//#region src/index.ts
+/** Built-in externals for the plugin (node) bundle. */
+const PLUGIN_EXTERNALS = ["@rspress/core"];
+/** Built-in externals for the runtime (browser) bundle — provided by RSPress at site build time. */
+const RUNTIME_EXTERNALS = [
+	"react",
+	"react/jsx-runtime",
+	"react/jsx-dev-runtime",
+	"@rspress/core",
+	"@theme"
+];
+/**
+* Build an RSPress plugin package: a Node plugin entry (`.`) plus a browser, bundleless,
+* CSS-module React runtime entry (`./runtime`). Returns a standard {@link BuildConfig};
+* hand it to {@link runBuild} from a self-executing `savvy.build.ts`.
+*/
+function definePlugin(options = {}) {
+	const runtimeOpt = options.runtime ?? true;
+	const runtimeEnabled = runtimeOpt !== false;
+	const runtimeTuning = typeof runtimeOpt === "object" ? runtimeOpt : {};
+	const pluginTuning = options.plugin ?? {};
+	const pluginExternals = [...PLUGIN_EXTERNALS, ...pluginTuning.externals ?? []];
+	const overrides = runtimeEnabled ? [{
+		entries: ["./runtime"],
+		outSubdir: "runtime",
+		platform: "browser",
+		css: {
+			modules: {
+				localsConvention: "camelCaseOnly",
+				namedExport: false
+			},
+			inject: true
+		},
+		externals: [...RUNTIME_EXTERNALS, ...runtimeTuning.externals ?? []]
+	}] : [];
+	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 } : {},
+		...options.transform !== void 0 ? { transform: options.transform } : {},
+		...options.jsx !== void 0 ? { jsx: options.jsx } : {},
+		...overrides.length > 0 ? { overrides } : {}
+	});
+}
+
+//#endregion
+export { definePlugin, runBuild };

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@savvy-web/rspress-builder",
+	"version": "0.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",
+	"bugs": {
+		"url": "https://github.com/savvy-web/systems/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/savvy-web/systems.git",
+		"directory": "packages/rspress-builder"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@savvyweb.systems",
+		"url": "https://savvyweb.systems"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./rspress-env.d.ts": "./public/rspress-env.d.ts",
+		"./tsconfig/ecma.json": "./public/ecma.json",
+		"./tsconfig/plugin.json": "./public/tsconfig/plugin.json",
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@savvy-web/bundler": "0.5.0",
+		"@savvy-web/tsdown-plugins": "0.5.0"
+	},
+	"peerDependencies": {
+		"@rspress/core": "^2.0.0",
+		"@tsdown/css": "^0.22.2",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0"
+	}
+}

package/public/ecma.json

@@ -0,0 +1,55 @@
+{
+	"$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": "es2025",
+		"tsBuildInfoFile": "${configDir}/dist/.tsbuildinfo.lib",
+		"typeRoots": ["${configDir}/node_modules/@types", "${configDir}/types"],
+		"verbatimModuleSyntax": true,
+		"types": ["node"]
+	},
+	"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"
+	]
+}

package/public/rspress-env.d.ts

@@ -0,0 +1,19 @@
+// 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;
+}

package/public/tsconfig/plugin.json

@@ -0,0 +1,11 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"compilerOptions": {
+		"jsx": "react-jsx",
+		"lib": ["es2025", "dom"],
+		"types": ["node", "react", "react-dom"]
+	},
+	"exclude": ["${configDir}/node_modules", "${configDir}/dist"],
+	"extends": "../ecma.json",
+	"include": ["${configDir}/types/*.d.ts", "${configDir}/src/**/*.ts", "${configDir}/src/**/*.tsx"]
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}