Cursor rule

1---
2alwaysApply: false
3---
4 
5## Prefer Statically Analyzable Paths
6 
7Build 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.
8 
9Prefer 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.
10 
11When analysis becomes too broad, the cost is real:
12- Larger server bundles
13- Slower builds
14- Worse cold starts
15- More memory use
16 
17### Import Paths
18 
19**Incorrect (the bundler cannot tell what may be imported):**
20 
21```ts
22const PAGE_MODULES = {
23  home: './pages/home',
24  settings: './pages/settings',
25} as const
26 
27const Page = await import(PAGE_MODULES[pageName])
28```
29 
30**Correct (use an explicit map of allowed modules):**
31 
32```ts
33const PAGE_MODULES = {
34  home: () => import('./pages/home'),
35  settings: () => import('./pages/settings'),
36} as const
37 
38const Page = await PAGE_MODULES[pageName]()
39```
40 
41### File-System Paths
42 
43**Incorrect (a 2-value enum still hides the final path from static analysis):**
44 
45```ts
46const baseDir = path.join(process.cwd(), 'content/' + contentKind)
47```
48 
49**Correct (make each final path literal at the callsite):**
50 
51```ts
52const baseDir =
53  kind === ContentKind.Blog
54    ? path.join(process.cwd(), 'content/blog')
55    : path.join(process.cwd(), 'content/docs')
56```
57 
58In 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.
59 
60Reference: [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/)
61