rspress-plugin-api-extractor 0.7.5 → 0.8.0

package/config-utils.js

@@ -15,6 +15,15 @@ function isLoadedModel(result) {
 	return typeof result === "object" && result !== null && "model" in result;
 }
 /**
+* Classify the `api` / `apis` options. Callers use `disabled` to skip doc
+* generation without failing the build, and `missing` to fail it.
+*/
+function classifyApiConfig(options) {
+	if (options.api != null) return "configured";
+	if (options.apis != null && options.apis.length > 0) return "configured";
+	return options.api !== void 0 || options.apis !== void 0 ? "disabled" : "missing";
+}
+/**
 * Normalize llmsPlugin config to always be an LlmsPlugin object
 */
 function normalizeLlmsPluginConfig(config) {
@@ -284,4 +293,4 @@ function validateExternalPackages(externalPackages, packageJson) {
 }
 
 //#endregion
-export { extractAutoDetectedPackages, extractPeerDependencies, extractTypeUtilities, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, normalizeLlmsPluginConfig, resolveExternalPackageVersions, resolvePackageVersionConflicts, validateExternalPackages };
+export { classifyApiConfig, extractAutoDetectedPackages, extractPeerDependencies, extractTypeUtilities, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, normalizeLlmsPluginConfig, resolveExternalPackageVersions, resolvePackageVersionConflicts, validateExternalPackages };

package/index.d.ts

@@ -398,11 +398,17 @@ type MultiApiConfig = typeof MultiApiConfig.Encoded;
 /**
  * Top-level options passed to {@link ApiExtractorPlugin}.
  *
+ * @remarks
+ * Supplying `api: null`, `apis: null` or `apis: []` opts into an inert plugin:
+ * the options are validated but no documentation is generated. This lets a site
+ * pre-configure the plugin before any API model exists. Omitting both keys
+ * entirely is still a configuration error.
+ *
  * @public
  */
 declare const PluginOptions: Schema.Struct<{
-  /** Single-API configuration (mutually exclusive with `apis`). */
-  readonly api: Schema.optional<Schema.Struct<{
+  /** Single-API configuration (mutually exclusive with `apis`). `null` disables generation. */
+  readonly api: Schema.optional<Schema.NullOr<Schema.Struct<{
     /** npm package name of the documented package. */
     readonly packageName: Schema.String;
     /** Optional display name shown in the sidebar and page titles. */
@@ -553,9 +559,9 @@ declare const PluginOptions: Schema.Struct<{
     readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
     /** TypeScript compiler options for Twoslash. */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
-  }>>;
-  /** Multi-API portal configuration (mutually exclusive with `api`). */
-  readonly apis: Schema.optional<Schema.mutable<Schema.$Array<Schema.Struct<{
+  }>>>;
+  /** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
+  readonly apis: Schema.optional<Schema.NullOr<Schema.mutable<Schema.$Array<Schema.Struct<{
     /** npm package name of the documented package. */
     readonly packageName: Schema.String;
     /** Optional display name shown in the sidebar and page titles. */
@@ -646,7 +652,7 @@ declare const PluginOptions: Schema.Struct<{
     readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
     /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
-  }>>>>;
+  }>>>>>;
   /** Canonical site URL used for Open Graph absolute URLs. */
   readonly siteUrl: Schema.optional<Schema.String>;
   /** Global Open Graph image configuration (overridden per-API). */

package/layers/ConfigServiceLive.js

@@ -8,7 +8,7 @@ import { OpenGraphResolver } from "../og-resolver.js";
 import { withPhase } from "../observability/spans.js";
 import { resolveTypeScriptConfig } from "../typescript-config.js";
 import { TwoslashManager } from "../twoslash-transformer.js";
-import { extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
+import { classifyApiConfig, extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
 import { ApiExtractedPackage } from "../api-extracted-package.js";
 import { CategoryResolver } from "../category-resolver.js";
 import { ConfigValidationError } from "../errors.js";
@@ -94,21 +94,21 @@ function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
 */
 function validateOptions(options, rspressConfig) {
 	return Effect.gen(function* () {
-		const { api, apis } = options;
+		const api = options.api ?? void 0;
+		const apis = options.apis != null && options.apis.length > 0 ? options.apis : void 0;
 		const { multiVersion } = rspressConfig;
 		if (api && apis) return yield* new ConfigValidationError({
 			field: "api/apis",
 			reason: "Cannot provide both 'api' and 'apis'. Use 'api' for single-package sites or 'apis' for multi-package portals."
 		});
-		if (!api && !apis) return yield* new ConfigValidationError({
-			field: "api/apis",
-			reason: "Must provide either 'api' or 'apis'."
-		});
-		if (apis) {
-			if (apis.length === 0) return yield* new ConfigValidationError({
-				field: "apis",
-				reason: "'apis' must contain at least one API configuration."
+		if (!api && !apis) {
+			if (classifyApiConfig(options) === "missing") return yield* new ConfigValidationError({
+				field: "api/apis",
+				reason: "Must provide either 'api' or 'apis'."
 			});
+			return;
+		}
+		if (apis) {
 			if (multiVersion) return yield* new ConfigValidationError({
 				field: "apis",
 				reason: "multiVersion is not supported with 'apis' (multi-API mode). Use 'api' (single-API mode) for versioned documentation."

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.7.5",
+	"version": "0.8.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [

package/plugin.js

@@ -12,7 +12,7 @@ import { VfsRegistry } from "./vfs-registry.js";
 import { generateApiDocs } from "./build-program.js";
 import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
 import { fromDir, fromParentDir } from "./config-helpers.js";
-import { mergeLlmsPluginConfig } from "./config-utils.js";
+import { classifyApiConfig, mergeLlmsPluginConfig } from "./config-utils.js";
 import { DEFAULT_SHIKI_THEMES, setShikiUtilsEventEmitter } from "./markdown/shiki-utils.js";
 import { setModelLoaderEventEmitter } from "./model-loader.js";
 import { resolveObservability } from "./schemas/observability.js";
@@ -73,6 +73,7 @@ function normalizeThemeConfig(theme) {
 */
 function ApiExtractorPluginImpl(rawOptions) {
 	const options = Schema.decodeUnknownSync(PluginOptions)(rawOptions);
+	const isInert = classifyApiConfig(options) === "disabled";
 	const shikiCrossLinker = new ShikiCrossLinker();
 	const envLogLevel = process.env.LOG_LEVEL?.toLowerCase();
 	const buildId = `${process.pid}-${performance.now().toString(36)}`;
@@ -112,7 +113,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 		name: "rspress-plugin-api-docs",
 		async beforeBuild(_config, _isProd) {},
 		async afterBuild(_config, isProd) {
-			if (isFirstBuild) {
+			if (isFirstBuild && !isInert) {
 				await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock));
 				if (isProd) await effectRuntime.runPromise(Effect.gen(function* () {
 					const packageName = yield* readSitePackageName;
@@ -183,7 +184,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 				key: dep.key,
 				replacement: dep.replacement
 			}));
-			try {
+			if (!isInert) try {
 				const rspressConfigSubset = {
 					...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
 					...rspressLocales.length > 0 ? { locales: rspressLocales.map((lang) => ({ lang })) } : {},
@@ -253,7 +254,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 			const updatedConfig = { ..._config };
 			if (!updatedConfig.builderConfig) updatedConfig.builderConfig = {};
 			if (!updatedConfig.builderConfig.source) updatedConfig.builderConfig.source = {};
-			if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
+			if (!isInert && rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
 				if (!updatedConfig.builderConfig.resolve) updatedConfig.builderConfig.resolve = {};
 				const pluginDir = path.dirname(fileURLToPath(import.meta.url));
 				const customLlmsViewOptions = path.resolve(pluginDir, "runtime/components/ApiLlmsViewOptions/index.js");
@@ -277,7 +278,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 				theme: remarkTheme
 			}]);
 			updatedConfig.markdown.remarkPlugins.push([remarkApiCodeblocks]);
-			if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
+			if (!isInert && rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
 				packageRoutes.clear();
 				if (options.api) packageRoutes.set(options.api.packageName, normalizeBaseRoute(options.api.baseRoute ?? "/"));
 				else if (options.apis) for (const api of options.apis) packageRoutes.set(api.packageName, normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`));

package/schemas/config.js

@@ -287,13 +287,19 @@ const MultiApiConfig = Schema.Struct({
 /**
 * Top-level options passed to {@link ApiExtractorPlugin}.
 *
+* @remarks
+* Supplying `api: null`, `apis: null` or `apis: []` opts into an inert plugin:
+* the options are validated but no documentation is generated. This lets a site
+* pre-configure the plugin before any API model exists. Omitting both keys
+* entirely is still a configuration error.
+*
 * @public
 */
 const PluginOptions = Schema.Struct({
-	/** Single-API configuration (mutually exclusive with `apis`). */
-	api: Schema.optional(SingleApiConfig),
-	/** Multi-API portal configuration (mutually exclusive with `api`). */
-	apis: Schema.optional(Schema.mutable(Schema.Array(MultiApiConfig))),
+	/** Single-API configuration (mutually exclusive with `apis`). `null` disables generation. */
+	api: Schema.optional(Schema.NullOr(SingleApiConfig)),
+	/** Multi-API portal configuration (mutually exclusive with `api`). `null` or `[]` disables generation. */
+	apis: Schema.optional(Schema.NullOr(Schema.mutable(Schema.Array(MultiApiConfig)))),
 	/** Canonical site URL used for Open Graph absolute URLs. */
 	siteUrl: Schema.optional(Schema.String),
 	/** Global Open Graph image configuration (overridden per-API). */