rspress-plugin-api-extractor 0.7.4 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/config-utils.js +10 -1
  2. package/env.d.ts +114 -0
  3. package/index.d.ts +12 -6
  4. package/layers/ConfigServiceLive.js +10 -10
  5. package/package.json +6 -3
  6. package/plugin.js +6 -5
  7. package/runtime/components/ApiExample/index.js +1 -1
  8. package/schemas/config.js +10 -4
  9. package/tsconfig/rspress.json +4 -1
package/config-utils.js CHANGED
@@ -15,6 +15,15 @@ function isLoadedModel(result) {
15
15
  return typeof result === "object" && result !== null && "model" in result;
16
16
  }
17
17
  /**
18
+ * Classify the `api` / `apis` options. Callers use `disabled` to skip doc
19
+ * generation without failing the build, and `missing` to fail it.
20
+ */
21
+ function classifyApiConfig(options) {
22
+ if (options.api != null) return "configured";
23
+ if (options.apis != null && options.apis.length > 0) return "configured";
24
+ return options.api !== void 0 || options.apis !== void 0 ? "disabled" : "missing";
25
+ }
26
+ /**
18
27
  * Normalize llmsPlugin config to always be an LlmsPlugin object
19
28
  */
20
29
  function normalizeLlmsPluginConfig(config) {
@@ -284,4 +293,4 @@ function validateExternalPackages(externalPackages, packageJson) {
284
293
  }
285
294
 
286
295
  //#endregion
287
- export { extractAutoDetectedPackages, extractPeerDependencies, extractTypeUtilities, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, normalizeLlmsPluginConfig, resolveExternalPackageVersions, resolvePackageVersionConflicts, validateExternalPackages };
296
+ export { classifyApiConfig, extractAutoDetectedPackages, extractPeerDependencies, extractTypeUtilities, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, normalizeLlmsPluginConfig, resolveExternalPackageVersions, resolvePackageVersionConflicts, validateExternalPackages };
package/env.d.ts ADDED
@@ -0,0 +1,114 @@
1
+ // // Ambient module + import.meta.env declarations for RSPress plugin runtimes built with
2
+ // // @savvy-web/rspress-builder. Replaces the rslib-era @rslib/core/types reference.
3
+
4
+ type CSSModuleClasses = Readonly<Record<string, string>>;
5
+
6
+ declare module "*.module.css" {
7
+ const classes: CSSModuleClasses;
8
+ export default classes;
9
+ }
10
+ declare module "*.css" {}
11
+
12
+ /**
13
+ * The `ImportMetaEnv` interface defines the shape of the `import.meta.env` object, which contains environment variables
14
+ * injected by Vite during the build process. These variables provide information about the build environment,
15
+ * such as whether the app is running in development or production mode, whether it is being server-side rendered, and other relevant details.
16
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
17
+ */
18
+ interface ImportMetaEnv {
19
+ /**
20
+ * Environment variable so React components can distinguish SSG-MD (markdown)
21
+ * rendering from browser rendering and customize their output
22
+ * @example
23
+ * ```typescript
24
+ * export function Tab({ label }: { label: string }) {
25
+ * if (import.meta.env.SSG_MD) {
26
+ * // This will be returned as a static string in the markdown output
27
+ * return <>{`** Here is a Tab named ${label}**`}</>;
28
+ * }
29
+ * // This will be returned as a React component in the browser
30
+ * return <div class="tab">{label}</div>;
31
+ * }
32
+ * ```
33
+ * @see {@link https://rspress.rs/guide/basic/ssg-md|RSPress | SSG-MD }
34
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
35
+ * */
36
+
37
+ readonly SSG_MD: boolean;
38
+ /**
39
+ * whether the Vite app is running in SSR (server-side rendering) mode. Allows you to
40
+ * conditionally render React components differently for SSR vs. browser rendering.
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * export function DebugInfo() {
45
+ * if (import.meta.env.SSR) {
46
+ * return <div class="debug-info">Debug info here</div>;
47
+ * }
48
+ * return null;
49
+ * }
50
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
51
+ */
52
+ readonly SSR: boolean;
53
+
54
+ /**
55
+ * Environment variable so React components can distinguish between development and
56
+ * production builds
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * export function DebugInfo() {
61
+ * if (import.meta.env.MODE === "development") {
62
+ * return <div class="debug-info">Debug info here</div>;
63
+ * }
64
+ * return null;
65
+ * }
66
+ * ```
67
+ * @see {@link https://vite.dev/guide/env-and-mode#modes|Vite | Modes }
68
+ */
69
+ readonly MODE: "development" | "production";
70
+
71
+ /**
72
+ * Base public path when served in development or production. Valid values include:
73
+ * Absolute URL pathname, e.g. `/foo/`
74
+ * - 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/)
75
+ * - Empty string or `./` (for embedded deployment)
76
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
77
+ */
78
+ readonly BASE_URL: string;
79
+
80
+ /**
81
+ * whether the Vite app is running in production mode:
82
+ * - running the dev server with `NODE_ENV='production'`
83
+ * - running an app built with `NODE_ENV='production'`)
84
+ *
85
+ * Always the opposite of `import.meta.env.DEV`
86
+ *
87
+ * @see {@link https://vite.dev/guide/env-and-mode#env-files|Vite | Modes }
88
+ */
89
+ readonly PROD: boolean;
90
+
91
+ /**
92
+ * whether the Vite app is running in development mode:
93
+ * - running the dev server with `NODE_ENV='development'`
94
+ * - running an app built with `NODE_ENV='development'`
95
+ *
96
+ * Always the opposite of `import.meta.env.PROD`.
97
+ * @see {@link https://vite.dev/guide/env-and-mode#env-files|Vite | Modes }
98
+ */
99
+ readonly DEV: boolean;
100
+ }
101
+
102
+ // biome-ignore lint/correctness/noUnusedVariables: ImportMeta is used by TypeScript but may appear unused to the linter
103
+ interface ImportMeta {
104
+ /**
105
+ * The `import.meta` object contains metadata about the current module. It is a standard
106
+ * feature in JavaScript modules. The `env` property on `import.meta` is a custom property injected
107
+ * by Vite that provides access to environment variables defined in the Vite configuration or `.env` files.
108
+ * RSPress uses this to provide information about the build environment, such as whether the app is running
109
+ * in development or production mode, whether it is being server-side rendered, and other relevant environment details.
110
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta|}
111
+ * @see {@link https://vite.dev/guide/env-and-mode|Vite | Env and Modes }
112
+ */
113
+ env: ImportMetaEnv;
114
+ }
package/index.d.ts CHANGED
@@ -398,11 +398,17 @@ type MultiApiConfig = typeof MultiApiConfig.Encoded;
398
398
  /**
399
399
  * Top-level options passed to {@link ApiExtractorPlugin}.
400
400
  *
401
+ * @remarks
402
+ * Supplying `api: null`, `apis: null` or `apis: []` opts into an inert plugin:
403
+ * the options are validated but no documentation is generated. This lets a site
404
+ * pre-configure the plugin before any API model exists. Omitting both keys
405
+ * entirely is still a configuration error.
406
+ *
401
407
  * @public
402
408
  */
403
409
  declare const PluginOptions: Schema.Struct<{
404
- /** Single-API configuration (mutually exclusive with `apis`). */
405
- readonly api: Schema.optional<Schema.Struct<{
410
+ /** Single-API configuration (mutually exclusive with `apis`). `null` disables generation. */
411
+ readonly api: Schema.optional<Schema.NullOr<Schema.Struct<{
406
412
  /** npm package name of the documented package. */
407
413
  readonly packageName: Schema.String;
408
414
  /** Optional display name shown in the sidebar and page titles. */
@@ -553,9 +559,9 @@ declare const PluginOptions: Schema.Struct<{
553
559
  readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
554
560
  /** TypeScript compiler options for Twoslash. */
555
561
  readonly compilerOptions: Schema.optional<Schema.Unknown>;
556
- }>>;
557
- /** Multi-API portal configuration (mutually exclusive with `api`). */
558
- readonly apis: Schema.optional<Schema.mutable<Schema.$Array<Schema.Struct<{
562
+ }>>>;
563
+ /** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
564
+ readonly apis: Schema.optional<Schema.NullOr<Schema.mutable<Schema.$Array<Schema.Struct<{
559
565
  /** npm package name of the documented package. */
560
566
  readonly packageName: Schema.String;
561
567
  /** Optional display name shown in the sidebar and page titles. */
@@ -646,7 +652,7 @@ declare const PluginOptions: Schema.Struct<{
646
652
  readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
647
653
  /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
648
654
  readonly compilerOptions: Schema.optional<Schema.Unknown>;
649
- }>>>>;
655
+ }>>>>>;
650
656
  /** Canonical site URL used for Open Graph absolute URLs. */
651
657
  readonly siteUrl: Schema.optional<Schema.String>;
652
658
  /** Global Open Graph image configuration (overridden per-API). */
package/layers/ConfigServiceLive.js CHANGED
@@ -8,7 +8,7 @@ import { OpenGraphResolver } from "../og-resolver.js";
8
8
  import { withPhase } from "../observability/spans.js";
9
9
  import { resolveTypeScriptConfig } from "../typescript-config.js";
10
10
  import { TwoslashManager } from "../twoslash-transformer.js";
11
- import { extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
11
+ import { classifyApiConfig, extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
12
12
  import { ApiExtractedPackage } from "../api-extracted-package.js";
13
13
  import { CategoryResolver } from "../category-resolver.js";
14
14
  import { ConfigValidationError } from "../errors.js";
@@ -94,21 +94,21 @@ function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
94
94
  */
95
95
  function validateOptions(options, rspressConfig) {
96
96
  return Effect.gen(function* () {
97
- const { api, apis } = options;
97
+ const api = options.api ?? void 0;
98
+ const apis = options.apis != null && options.apis.length > 0 ? options.apis : void 0;
98
99
  const { multiVersion } = rspressConfig;
99
100
  if (api && apis) return yield* new ConfigValidationError({
100
101
  field: "api/apis",
101
102
  reason: "Cannot provide both 'api' and 'apis'. Use 'api' for single-package sites or 'apis' for multi-package portals."
102
103
  });
103
- if (!api && !apis) return yield* new ConfigValidationError({
104
- field: "api/apis",
105
- reason: "Must provide either 'api' or 'apis'."
106
- });
107
- if (apis) {
108
- if (apis.length === 0) return yield* new ConfigValidationError({
109
- field: "apis",
110
- reason: "'apis' must contain at least one API configuration."
104
+ if (!api && !apis) {
105
+ if (classifyApiConfig(options) === "missing") return yield* new ConfigValidationError({
106
+ field: "api/apis",
107
+ reason: "Must provide either 'api' or 'apis'."
111
108
  });
109
+ return;
110
+ }
111
+ if (apis) {
112
112
  if (multiVersion) return yield* new ConfigValidationError({
113
113
  field: "apis",
114
114
  reason: "multiVersion is not supported with 'apis' (multi-API mode). Use 'api' (single-API mode) for versioned documentation."
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rspress-plugin-api-extractor",
3
- "version": "0.7.4",
3
+ "version": "0.8.0",
4
4
  "private": false,
5
5
  "description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
6
6
  "keywords": [
@@ -25,6 +25,9 @@
25
25
  "import": "./index.js",
26
26
  "default": "./index.js"
27
27
  },
28
+ "./env": {
29
+ "types": "./env.d.ts"
30
+ },
28
31
  "./runtime": {
29
32
  "types": "./runtime/index.d.ts",
30
33
  "import": "./runtime/index.js",
@@ -38,7 +41,7 @@
38
41
  "@effect/sql-sqlite-node": "4.0.0-beta.101",
39
42
  "@effected/semver": "^0.2.1",
40
43
  "@effected/store": "^0.1.2",
41
- "@effected/tsconfig-json": "^0.3.3",
44
+ "@effected/tsconfig-json": "^0.4.0",
42
45
  "@effected/xdg": "^0.1.9",
43
46
  "@microsoft/api-extractor-model": "^7.33.10",
44
47
  "@shikijs/twoslash": "^4.3.1",
@@ -56,7 +59,7 @@
56
59
  "prettier": "^3.9.6",
57
60
  "react-markdown": "^10.1.0",
58
61
  "shiki": "^4.3.1",
59
- "type-registry-effect": "^2.3.0",
62
+ "type-registry-effect": "^2.3.1",
60
63
  "typescript": "^6.0.3",
61
64
  "unist-util-visit": "^5.1.0"
62
65
  },
package/plugin.js CHANGED
@@ -12,7 +12,7 @@ import { VfsRegistry } from "./vfs-registry.js";
12
12
  import { generateApiDocs } from "./build-program.js";
13
13
  import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
14
14
  import { fromDir, fromParentDir } from "./config-helpers.js";
15
- import { mergeLlmsPluginConfig } from "./config-utils.js";
15
+ import { classifyApiConfig, mergeLlmsPluginConfig } from "./config-utils.js";
16
16
  import { DEFAULT_SHIKI_THEMES, setShikiUtilsEventEmitter } from "./markdown/shiki-utils.js";
17
17
  import { setModelLoaderEventEmitter } from "./model-loader.js";
18
18
  import { resolveObservability } from "./schemas/observability.js";
@@ -73,6 +73,7 @@ function normalizeThemeConfig(theme) {
73
73
  */
74
74
  function ApiExtractorPluginImpl(rawOptions) {
75
75
  const options = Schema.decodeUnknownSync(PluginOptions)(rawOptions);
76
+ const isInert = classifyApiConfig(options) === "disabled";
76
77
  const shikiCrossLinker = new ShikiCrossLinker();
77
78
  const envLogLevel = process.env.LOG_LEVEL?.toLowerCase();
78
79
  const buildId = `${process.pid}-${performance.now().toString(36)}`;
@@ -112,7 +113,7 @@ function ApiExtractorPluginImpl(rawOptions) {
112
113
  name: "rspress-plugin-api-docs",
113
114
  async beforeBuild(_config, _isProd) {},
114
115
  async afterBuild(_config, isProd) {
115
- if (isFirstBuild) {
116
+ if (isFirstBuild && !isInert) {
116
117
  await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock));
117
118
  if (isProd) await effectRuntime.runPromise(Effect.gen(function* () {
118
119
  const packageName = yield* readSitePackageName;
@@ -183,7 +184,7 @@ function ApiExtractorPluginImpl(rawOptions) {
183
184
  key: dep.key,
184
185
  replacement: dep.replacement
185
186
  }));
186
- try {
187
+ if (!isInert) try {
187
188
  const rspressConfigSubset = {
188
189
  ...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
189
190
  ...rspressLocales.length > 0 ? { locales: rspressLocales.map((lang) => ({ lang })) } : {},
@@ -253,7 +254,7 @@ function ApiExtractorPluginImpl(rawOptions) {
253
254
  const updatedConfig = { ..._config };
254
255
  if (!updatedConfig.builderConfig) updatedConfig.builderConfig = {};
255
256
  if (!updatedConfig.builderConfig.source) updatedConfig.builderConfig.source = {};
256
- if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
257
+ if (!isInert && rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
257
258
  if (!updatedConfig.builderConfig.resolve) updatedConfig.builderConfig.resolve = {};
258
259
  const pluginDir = path.dirname(fileURLToPath(import.meta.url));
259
260
  const customLlmsViewOptions = path.resolve(pluginDir, "runtime/components/ApiLlmsViewOptions/index.js");
@@ -277,7 +278,7 @@ function ApiExtractorPluginImpl(rawOptions) {
277
278
  theme: remarkTheme
278
279
  }]);
279
280
  updatedConfig.markdown.remarkPlugins.push([remarkApiCodeblocks]);
280
- if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
281
+ if (!isInert && rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
281
282
  packageRoutes.clear();
282
283
  if (options.api) packageRoutes.set(options.api.packageName, normalizeBaseRoute(options.api.baseRoute ?? "/"));
283
284
  else if (options.apis) for (const api of options.apis) packageRoutes.set(api.packageName, normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`));
package/runtime/components/ApiExample/index.js CHANGED
@@ -15,7 +15,7 @@ import { Fragment, jsx } from "react/jsx-runtime";
15
15
  */
16
16
  function ApiExample({ code, hast }) {
17
17
  const parsedHast = useMemo(() => decodeHast(hast, "ApiExample"), [hast]);
18
- if (import.meta.env.SSG_MD) return /* @__PURE__ */ jsx(Fragment, { children: `\`\`\`typescript
18
+ if (import.meta.env?.SSG_MD === true) return /* @__PURE__ */ jsx(Fragment, { children: `\`\`\`typescript
19
19
  ${code.trim()}
20
20
  \`\`\`
21
21
  ` });
package/schemas/config.js CHANGED
@@ -287,13 +287,19 @@ const MultiApiConfig = Schema.Struct({
287
287
  /**
288
288
  * Top-level options passed to {@link ApiExtractorPlugin}.
289
289
  *
290
+ * @remarks
291
+ * Supplying `api: null`, `apis: null` or `apis: []` opts into an inert plugin:
292
+ * the options are validated but no documentation is generated. This lets a site
293
+ * pre-configure the plugin before any API model exists. Omitting both keys
294
+ * entirely is still a configuration error.
295
+ *
290
296
  * @public
291
297
  */
292
298
  const PluginOptions = Schema.Struct({
293
- /** Single-API configuration (mutually exclusive with `apis`). */
294
- api: Schema.optional(SingleApiConfig),
295
- /** Multi-API portal configuration (mutually exclusive with `api`). */
296
- apis: Schema.optional(Schema.mutable(Schema.Array(MultiApiConfig))),
299
+ /** Single-API configuration (mutually exclusive with `apis`). `null` disables generation. */
300
+ api: Schema.optional(Schema.NullOr(SingleApiConfig)),
301
+ /** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
302
+ apis: Schema.optional(Schema.NullOr(Schema.mutable(Schema.Array(MultiApiConfig)))),
297
303
  /** Canonical site URL used for Open Graph absolute URLs. */
298
304
  siteUrl: Schema.optional(Schema.String),
299
305
  /** Global Open Graph image configuration (overridden per-API). */
package/tsconfig/rspress.json CHANGED
@@ -36,7 +36,10 @@
36
36
  "${configDir}/docs/**/*.mdx",
37
37
  "${configDir}/theme/**/*.ts",
38
38
  "${configDir}/theme/**/*.tsx",
39
- "${configDir}/theme/**/*.mdx"
39
+ "${configDir}/theme/**/*.mdx",
40
+ "${configDir}/components/**/*.ts",
41
+ "${configDir}/components/**/*.tsx",
42
+ "${configDir}/components/**/*.mdx"
40
43
  ],
41
44
  "mdx": {
42
45
  "checkMdx": true