Cursor rule

1---
2alwaysApply: false
3---
4 
5## Avoid Barrel File Imports
6 
7Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
8 
9Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
10 
11**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
12 
13**Incorrect (imports entire library):**
14 
15```tsx
16import { Check, X, Menu } from 'lucide-react'
17// Loads 1,583 modules, takes ~2.8s extra in dev
18// Runtime cost: 200-800ms on every cold start
19 
20import { Button, TextField } from '@mui/material'
21// Loads 2,225 modules, takes ~4.2s extra in dev
22```
23 
24**Correct - Next.js 13.5+ (recommended):**
25 
26```js
27// next.config.js - automatically optimizes barrel imports at build time
28module.exports = {
29  experimental: {
30    optimizePackageImports: ['lucide-react', '@mui/material']
31  }
32}
33```
34 
35```tsx
36// Keep the standard imports - Next.js transforms them to direct imports
37import { Check, X, Menu } from 'lucide-react'
38// Full TypeScript support, no manual path wrangling
39```
40 
41This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
42 
43**Correct - Direct imports (non-Next.js projects):**
44 
45```tsx
46import Button from '@mui/material/Button'
47import TextField from '@mui/material/TextField'
48// Loads only what you use
49```
50 
51> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
52 
53These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
54 
55Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
56 
57Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
58