fix: resolve React 18 via webpack plugin, add --scan-dir flag

Author: cryptodev-2s

eslint.config.mjs

@@ -16,6 +16,7 @@ const config = createConfig([
       '.yarn/**',
       'scripts/create-package/package-template/**',
       '.messenger-docs/**',
+      'packages/messenger-docs/template/**',
     ],
   },
   {

packages/messenger-docs/src/cli.ts

@@ -85,6 +85,7 @@ async function main(): Promise<void> {
   let dev = false;
   let outputDir: string | undefined;
   let projectPath: string | undefined;
+  const scanDirs: string[] = [];
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -107,6 +108,15 @@ async function main(): Promise<void> {
           return;
         }
         break;
+      case '--scan-dir':
+        i += 1;
+        if (!args[i] || args[i].startsWith('-')) {
+          console.error('Error: --scan-dir requires a path argument');
+          process.exitCode = 1;
+          return;
+        }
+        scanDirs.push(args[i]);
+        break;
       case '--help':
         printHelp();
         return;
@@ -132,6 +142,7 @@ async function main(): Promise<void> {
   await generate({
     projectPath: resolvedProjectPath,
     outputDir: resolvedOutputDir,
+    ...(scanDirs.length > 0 ? { scanDirs } : {}),
   });
 
   // Step 2: If --build, --serve, or --dev, set up and run Docusaurus
@@ -140,25 +151,6 @@ async function main(): Promise<void> {
 
     const { bin: docusaurus, nodeModules } = resolveDocusaurus();
 
-    // Symlink node_modules into the output directory so Docusaurus resolves
-    // React 18 and other deps from this package, not the host project.
-    const nmLink = path.join(resolvedOutputDir, 'node_modules');
-    try {
-      await fs.lstat(nmLink);
-      // Already exists — remove only if it's a symlink we previously created.
-      const target = await fs.readlink(nmLink).catch(() => null);
-      if (target !== null) {
-        await fs.unlink(nmLink);
-      }
-    } catch {
-      // Doesn't exist yet — nothing to remove.
-    }
-    try {
-      await fs.access(nmLink);
-    } catch {
-      await fs.symlink(nodeModules, nmLink);
-    }
-
     if (dev) {
       console.log('\nStarting dev server...');
       await runDocusaurus(docusaurus, 'start', resolvedOutputDir, nodeModules);
@@ -242,25 +234,27 @@ function printHelp(): void {
 Usage: messenger-docs [project-path] [options]
 
 Generate Messenger API documentation for MetaMask controller packages.
-Automatically scans both packages/*/src (.ts) and node_modules/@metamask (.d.cts).
+Scans packages/*/src (.ts), configured source dirs, and node_modules/@metamask (.d.cts).
 
 Arguments:
-  project-path    Path to the project to scan (default: current directory)
+  project-path      Path to the project to scan (default: current directory)
 
 Options:
-  --build         Generate docs and build static site
-  --serve         Generate docs, build, and serve static site
-  --dev           Generate docs and start dev server with hot reload
-  --output <dir>  Output directory (default: <project-path>/.messenger-docs)
-  --help          Show this help message
+  --build           Generate docs and build static site
+  --serve           Generate docs, build, and serve static site
+  --dev             Generate docs and start dev server with hot reload
+  --scan-dir <dir>  Extra source directory to scan (repeatable, default: src)
+  --output <dir>    Output directory (default: <project-path>/.messenger-docs)
+  --help            Show this help message
+
+Source directories can also be configured in package.json:
+  "messenger-docs": { "scanDirs": ["app", "src"] }
 
 Examples:
-  messenger-docs                           # Scan cwd for controller packages
-  messenger-docs /path/to/project          # Scan a specific project
-  messenger-docs --dev                     # Dev server with hot reload
-  messenger-docs --build                   # Generate and build static site
-  messenger-docs --serve                   # Generate, build, and serve
-  messenger-docs --output ./my-docs        # Custom output directory
+  messenger-docs                                   # Scan cwd
+  messenger-docs --serve                           # Generate, build, and serve
+  messenger-docs --scan-dir app --scan-dir shared  # Scan app/ and shared/
+  messenger-docs --output ./my-docs                # Custom output directory
 `);
 }
 

packages/messenger-docs/src/generate.ts

@@ -50,6 +50,12 @@ export type GenerateOptions = {
   projectPath: string;
   /** Absolute path to the output directory for generated docs. */
   outputDir: string;
+  /**
+   * Extra directories (relative to projectPath) to scan for .ts source files.
+   * When omitted, falls back to `"messenger-docs".scanDirs` in the project's
+   * package.json, then to `["src"]`.
+   */
+  scanDirs?: string[];
 };
 
 /**
@@ -70,21 +76,47 @@ export type GenerateResult = {
 export async function generate(
   options: GenerateOptions,
 ): Promise<GenerateResult> {
-  const { projectPath, outputDir } = options;
+  const { projectPath, outputDir, scanDirs: scanDirsOption } = options;
+
+  // Resolve scanDirs: CLI flag → package.json config → default ["src"]
+  let scanDirs = scanDirsOption;
+  if (!scanDirs) {
+    try {
+      const pkgRaw = await fs.readFile(
+        path.join(projectPath, 'package.json'),
+        'utf8',
+      );
+      const pkg = JSON.parse(pkgRaw) as Record<string, unknown>;
+      const config = pkg['messenger-docs'] as
+        | { scanDirs?: string[] }
+        | undefined;
+      if (Array.isArray(config?.scanDirs)) {
+        scanDirs = config.scanDirs;
+      }
+    } catch {
+      // No package.json or invalid — use default.
+    }
+    scanDirs ??= ['src'];
+  }
 
   const allItems: MessengerItemDoc[] = [];
 
   // Check which sources are available
-  const rootSrcDir = path.join(projectPath, 'src');
-  const hasRootSrc = await pathExists(rootSrcDir);
+  const existingScanDirs: string[] = [];
+  for (const dir of scanDirs) {
+    const abs = path.join(projectPath, dir);
+    if (await pathExists(abs)) {
+      existingScanDirs.push(dir);
+    }
+  }
   const packagesDir = path.join(projectPath, 'packages');
   const hasPackages = await pathExists(packagesDir);
   const nmDir = path.join(projectPath, 'node_modules', '@metamask');
   const hasNodeModules = await pathExists(nmDir);
 
   const sources: string[] = [];
-  if (hasRootSrc) {
-    sources.push('src/ (.ts)');
+  for (const dir of existingScanDirs) {
+    sources.push(`${dir}/ (.ts)`);
   }
   if (hasPackages) {
     sources.push('packages/*/src (.ts)');
@@ -96,9 +128,10 @@ export async function generate(
     `Scanning ${sources.join(', ')} for Messenger action/event types...`,
   );
 
-  // Scan project-level src/ for .ts source files
-  if (hasRootSrc) {
-    const tsFiles = await findTsFiles(rootSrcDir);
+  // Scan configured source directories for .ts files
+  for (const dir of existingScanDirs) {
+    const abs = path.join(projectPath, dir);
+    const tsFiles = await findTsFiles(abs);
     for (const file of tsFiles) {
       try {
         const items = await extractFromFile(file, projectPath);
@@ -172,9 +205,10 @@ export async function generate(
     }
   }
 
-  if (!hasRootSrc && !hasPackages && !hasNodeModules) {
+  if (existingScanDirs.length === 0 && !hasPackages && !hasNodeModules) {
     throw new Error(
-      `No src/, packages/, or node_modules/@metamask/ found in ${projectPath}.`,
+      `No scannable directories found in ${projectPath}. ` +
+        `Looked for: ${scanDirs.join(', ')}, packages/, node_modules/@metamask/`,
     );
   }
 

packages/messenger-docs/template/docusaurus.config.ts

@@ -1,9 +1,22 @@
+import * as path from 'node:path';
+
 import type * as Preset from '@docusaurus/preset-classic';
 import type { Config } from '@docusaurus/types';
 import { themes } from 'prism-react-renderer';
 
 const codeTheme = themes.dracula;
 
+// When running inside a host project (e.g. metamask-extension) whose React
+// version differs from Docusaurus's, we alias react/react-dom to the copies
+// installed alongside this package.
+const extraNodeModules = process.env.NODE_PATH; // eslint-disable-line no-process-env
+const reactAlias: Record<string, string> = {};
+if (extraNodeModules) {
+  for (const pkg of ['react', 'react-dom', '@mdx-js/react']) {
+    reactAlias[pkg] = path.join(extraNodeModules, pkg);
+  }
+}
+
 const config: Config = {
   title: 'Messenger API',
   tagline: 'Action and event reference for MetaMask controller messengers',
@@ -24,6 +37,22 @@ const config: Config = {
     locales: ['en'],
   },
 
+  plugins: [
+    function resolvePlugin() {
+      return {
+        name: 'resolve-deps',
+        configureWebpack() {
+          if (Object.keys(reactAlias).length === 0) {
+            return {};
+          }
+          return {
+            resolve: { alias: reactAlias },
+          };
+        },
+      };
+    },
+  ],
+
   themes: [
     [
       '@easyops-cn/docusaurus-search-local',