Merge pull request #226 from vercel-labs/shu/vPV6R

react-best-practices: Prefer Statically Analyzable Paths

Author: shuding

packages/react-best-practices-build/test-cases.json

@@ -159,6 +159,38 @@
     "language": "tsx",
     "description": "wrapper shows immediately, data streams in"
   },
+  {
+    "ruleId": "",
+    "ruleTitle": "Prefer Statically Analyzable Paths",
+    "type": "bad",
+    "code": "const PAGE_MODULES = {\n  home: './pages/home',\n  settings: './pages/settings',\n} as const\n\nconst Page = await import(PAGE_MODULES[pageName])",
+    "language": "ts",
+    "description": "the bundler cannot tell what may be imported"
+  },
+  {
+    "ruleId": "",
+    "ruleTitle": "Prefer Statically Analyzable Paths",
+    "type": "good",
+    "code": "const PAGE_MODULES = {\n  home: () => import('./pages/home'),\n  settings: () => import('./pages/settings'),\n} as const\n\nconst Page = await PAGE_MODULES[pageName]()",
+    "language": "ts",
+    "description": "use an explicit map of allowed modules"
+  },
+  {
+    "ruleId": "",
+    "ruleTitle": "Prefer Statically Analyzable Paths",
+    "type": "bad",
+    "code": "const CONTENT_DIRS = {\n  blog: 'content/blog',\n  docs: 'content/docs',\n} as const\n\nconst baseDir = path.join(process.cwd(), CONTENT_DIRS[contentKind])",
+    "language": "ts",
+    "description": "a 2-value enum still hides the final path from static analysis"
+  },
+  {
+    "ruleId": "",
+    "ruleTitle": "Prefer Statically Analyzable Paths",
+    "type": "good",
+    "code": "const baseDir =\n  kind === ContentKind.Blog\n    ? path.join(process.cwd(), 'content/blog')\n    : path.join(process.cwd(), 'content/docs')",
+    "language": "ts",
+    "description": "make each final path literal at the callsite"
+  },
   {
     "ruleId": "",
     "ruleTitle": "Avoid Barrel File Imports",

skills/react-best-practices/AGENTS.md

@@ -32,7 +32,8 @@ Comprehensive performance optimization guide for React and Next.js applications,
    - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
    - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
    - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
-   - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)
+   - 2.5 [Prefer Statically Analyzable Paths](#25-prefer-statically-analyzable-paths)
+   - 2.6 [Preload Based on User Intent](#26-preload-based-on-user-intent)
 3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
    - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
    - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
@@ -578,7 +579,71 @@ function CodePanel({ code }: { code: string }) {
 }
 ```
 
-### 2.5 Preload Based on User Intent
+### 2.5 Prefer Statically Analyzable Paths
+
+**Impact: HIGH (avoids accidental broad bundles and file traces)**
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+
+- Larger server bundles
+
+- Slower builds
+
+- Worse cold starts
+
+- More memory use
+
+**Incorrect: the bundler cannot tell what may be imported**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct: use an explicit map of allowed modules**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+**Incorrect: a 2-value enum still hides the final path from static analysis**
+
+```ts
+const CONTENT_DIRS = {
+  blog: 'content/blog',
+  docs: 'content/docs',
+} as const
+
+const baseDir = path.join(process.cwd(), CONTENT_DIRS[contentKind])
+```
+
+**Correct: make each final path literal at the callsite**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [https://nextjs.org/docs/app/api-reference/config/next-config-js/output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [https://nextjs.org/learn/seo/dynamic-imports](https://nextjs.org/learn/seo/dynamic-imports), [https://vite.dev/guide/features.html](https://vite.dev/guide/features.html), [https://esbuild.github.io/api/](https://esbuild.github.io/api/), [https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [https://webpack.js.org/guides/dependency-management/](https://webpack.js.org/guides/dependency-management/)
+
+### 2.6 Preload Based on User Intent
 
 **Impact: MEDIUM (reduces perceived latency)**
 

skills/react-best-practices/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 # Vercel React Best Practices
 
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
 
 ## When to Apply
 
@@ -47,6 +47,7 @@ Reference these guidelines when:
 ### 2. Bundle Size Optimization (CRITICAL)
 
 - `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
 - `bundle-dynamic-imports` - Use next/dynamic for heavy components
 - `bundle-defer-third-party` - Load analytics/logging after hydration
 - `bundle-conditional` - Load modules only when feature is activated

skills/react-best-practices/rules/bundle-analyzable-paths.md

@@ -0,0 +1,68 @@
+---
+title: Prefer Statically Analyzable Paths
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, nextjs, vite, webpack, rollup, esbuild, path
+---
+
+## Prefer Statically Analyzable Paths
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+- Larger server bundles
+- Slower builds
+- Worse cold starts
+- More memory use
+
+### Import Paths
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+### File-System Paths
+
+**Incorrect (a 2-value enum still hides the final path from static analysis):**
+
+```ts
+const CONTENT_DIRS = {
+  blog: 'content/blog',
+  docs: 'content/docs',
+} as const
+
+const baseDir = path.join(process.cwd(), CONTENT_DIRS[contentKind])
+```
+
+**Correct (make each final path literal at the callsite):**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)