@rspress/plugin-api-docgen 2.0.0 → 2.0.1

package/dist/index.js

@@ -1,8 +1,51 @@
 import node_fs from "node:fs";
-import node_path from "node:path";
-import { RSPRESS_TEMP_DIR, logger } from "@rspress/core";
-import chokidar from "chokidar";
+import node_path, { extname, join } from "node:path";
+import { logger } from "@rspress/core";
 import { withCompilerOptions, withCustomConfig, withDefaultConfig } from "react-docgen-typescript";
+const PLUGIN_VIRTUAL_MODULE_NAME = 'rsbuild:virtual-module';
+const pluginVirtualModule = (pluginOptions = {})=>({
+        name: PLUGIN_VIRTUAL_MODULE_NAME,
+        async setup (api) {
+            const { virtualModules = {}, tempDir: virtualFolderName = '.rsbuild-virtual-module' } = pluginOptions;
+            const TEMP_DIR = join(api.context.rootPath, virtualFolderName);
+            const virtualFileAbsolutePaths = Object.keys(virtualModules).map((i)=>{
+                let absolutePath = join(TEMP_DIR, i);
+                if (!extname(absolutePath)) absolutePath = `${absolutePath}.js`;
+                return [
+                    i,
+                    absolutePath
+                ];
+            });
+            api.modifyBundlerChain((chain, { rspack })=>{
+                const pluginId = 'RSBUILD_VIRTUAL_MODULE_PLUGIN';
+                const virtualModules = Object.fromEntries(virtualFileAbsolutePaths.map((i)=>[
+                        i[1],
+                        ''
+                    ]));
+                if (chain.plugins.has(pluginId)) chain.plugin(pluginId).tap((options)=>{
+                    const existingPaths = new Set(Object.keys(options[0] ?? {}));
+                    const conflictPath = virtualFileAbsolutePaths.find(([, path])=>existingPaths.has(path));
+                    if (conflictPath) throw new Error(`Virtual module name conflicted: ${conflictPath[0]}`);
+                    return [
+                        {
+                            ...options[0],
+                            ...virtualModules
+                        }
+                    ];
+                });
+                else chain.plugin(pluginId).use(rspack.experiments.VirtualModulesPlugin, [
+                    virtualModules
+                ]);
+                chain.resolve.alias.merge(Object.fromEntries(virtualFileAbsolutePaths));
+            });
+            for (const [moduleName, absolutePath] of virtualFileAbsolutePaths){
+                const handler = virtualModules[moduleName];
+                if (handler) api.transform({
+                    test: absolutePath
+                }, handler);
+            }
+        }
+    });
 node_path.join(__dirname, '..');
 const apiDocMap = {};
 const locales = {
@@ -56,16 +99,13 @@ const locales = {
     }
 };
 const isToolEntries = (obj)=>!!obj.documentation || !!obj["react-docgen-typescript"];
-const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptions, isProd })=>{
-    const watchFileMap = {};
+const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptions })=>{
+    const sourceFilePaths = [];
     const genApiDoc = async (entry, tool)=>{
         if (0 === Object.keys(entry).length) return;
         await Promise.all(Object.entries(entry).map(async ([key, value])=>{
             const moduleSourceFilePath = node_path.resolve(appDir, value);
-            watchFileMap[moduleSourceFilePath] = {
-                apiParseTool,
-                moduleName: key
-            };
+            sourceFilePaths.push(moduleSourceFilePath);
             try {
                 if ('documentation' === tool) {
                     const documentation = await import("documentation");
@@ -113,42 +153,8 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
             genApiDoc(documentationEntries, 'documentation')
         ]);
     } else await genApiDoc(entries, apiParseTool);
-    if (!isProd) {
-        const watcher = chokidar.watch(Object.keys(watchFileMap), {
-            ignoreInitial: true,
-            ignorePermissionErrors: true,
-            ignored: [
-                /node_modules/
-            ]
-        });
-        let isUpdate = false;
-        watcher.on('change', (changed)=>{
-            if (isUpdate) return;
-            isUpdate = true;
-            logger.info('[module-doc-plugin]', 'updating API');
-            const watchFileInfo = watchFileMap[changed];
-            if (watchFileInfo) {
-                const { apiParseTool, moduleName } = watchFileInfo;
-                const updateSiteData = ()=>{
-                    const siteDataPath = node_path.join(process.cwd(), 'node_modules', RSPRESS_TEMP_DIR, 'runtime', 'virtual-site-data.mjs');
-                    import(siteDataPath).then((siteData)=>{
-                        const data = {
-                            ...siteData.default
-                        };
-                        data.pages.forEach((page)=>{
-                            page.apiDocMap = apiDocMap;
-                        });
-                        node_fs.writeFileSync(siteDataPath, `export default ${JSON.stringify(data)}`);
-                        isUpdate = false;
-                    });
-                };
-                genApiDoc({
-                    [moduleName]: changed
-                }, apiParseTool).then(updateSiteData);
-            }
-        });
-    }
     logger.success('[module-doc-plugin]', 'Generate API table successfully!');
+    return sourceFilePaths;
 };
 function generateTable(componentDoc, language) {
     return componentDoc.map((param)=>{
@@ -197,6 +203,7 @@ function generateTable(componentDoc, language) {
     `;
     }).join('\n');
 }
+const VIRTUAL_MODULE_NAME = 'rspress-plugin-api-docgen-map';
 function pluginApiDocgen(options) {
     const { entries = {}, apiParseTool = "react-docgen-typescript", appDir = process.cwd(), parseToolOptions = {} } = options || {};
     return {
@@ -205,7 +212,7 @@ function pluginApiDocgen(options) {
             config.markdown = config.markdown || {};
             return config;
         },
-        async beforeBuild (config, isProd) {
+        async beforeBuild (config) {
             let languages = (config.themeConfig?.locales?.map((locale)=>locale.lang) || config.locales?.map((locale)=>locale.lang) || []).filter((lang)=>[
                     'zh',
                     'en',
@@ -215,20 +222,29 @@ function pluginApiDocgen(options) {
             if (0 === languages.length) languages = [
                 defaultLang
             ];
-            await docgen({
+            const docgenOptions = {
                 entries,
                 apiParseTool,
                 languages,
                 appDir,
-                parseToolOptions,
-                isProd
-            });
-            config.builderConfig = config.builderConfig || {};
-            config.builderConfig.source = config.builderConfig.source || {};
-            config.builderConfig.source.define = {
-                ...config.builderConfig.source.define,
-                RSPRESS_PLUGIN_API_DOCGEN_MAP: JSON.stringify(apiDocMap)
+                parseToolOptions
             };
+            const sourceFiles = await docgen(docgenOptions);
+            let isFirstTransform = true;
+            config.builderConfig = config.builderConfig || {};
+            config.builderConfig.plugins = [
+                ...config.builderConfig.plugins || [],
+                pluginVirtualModule({
+                    virtualModules: {
+                        [VIRTUAL_MODULE_NAME]: async ({ addDependency })=>{
+                            if (isFirstTransform) isFirstTransform = false;
+                            else await docgen(docgenOptions);
+                            for (const filePath of sourceFiles)addDependency(filePath);
+                            return `export default ${JSON.stringify(apiDocMap)};`;
+                        }
+                    }
+                })
+            ];
         },
         async modifySearchIndexData (pages) {
             const apiCompRegExp = /(<API\s+moduleName=['"](\S+)['"]\s*(.*)?\/>)|(<API\s+moduleName=['"](\S+)['"]\s*(.*)?>(.*)?<\/API>)/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rspress/plugin-api-docgen",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A plugin for rspress to generate api doc.",
   "bugs": "https://github.com/web-infra-dev/rspress/issues",
   "repository": {
@@ -22,7 +22,6 @@
     "static"
   ],
   "dependencies": {
-    "chokidar": "^3.6.0",
     "documentation": "14.0.3",
     "github-slugger": "^2.0.0",
     "react-docgen-typescript": "2.4.0",
@@ -43,10 +42,11 @@
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.12.0",
     "rsbuild-plugin-publint": "^0.3.4",
+    "rsbuild-plugin-virtual-module": "0.4.1",
     "typescript": "^5.8.2"
   },
   "peerDependencies": {
-    "@rspress/core": "^2.0.0",
+    "@rspress/core": "^2.0.1",
     "typescript": "^5.8.2"
   },
   "peerDependenciesMeta": {
@@ -55,7 +55,7 @@
     }
   },
   "engines": {
-    "node": ">=20.9.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/static/global-components/API.tsx

@@ -8,13 +8,11 @@ import remarkGfm from 'remark-gfm';
 import './API.css';
 // biome-ignore lint/style/useImportType: <exact>
 import React from 'react';
+// @ts-expect-error virtual module
+import apiDocMap from 'rspress-plugin-api-docgen-map';
 import type { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
-declare global {
-  var RSPRESS_PLUGIN_API_DOCGEN_MAP: Record<string, string>;
-}
-
 function headingRank(node: Root | Content): number | null {
   const name =
     (node && node.type === 'element' && node.tagName.toLowerCase()) || '';
@@ -103,9 +101,6 @@ const collectHeaderText = (node: Element): string => {
 const API = (props: { moduleName: string }) => {
   const lang = useLang();
   const { moduleName } = props;
-  // some api doc have two languages.
-  const apiDocMap = RSPRESS_PLUGIN_API_DOCGEN_MAP;
-  // avoid error when no page data
   const apiDoc = apiDocMap?.[`${moduleName}-${lang}`] || '';
   return (
     <div className="rspress-plugin-api-docgen">