bundle-barrel-imports — Claude Code rule: what it does, install
The bundle-barrel-imports rule steers imports away from barrel files and toward source modules. It helps when a package exposes many re-exports and slows loading.
MIT ★ 7,191 updated 2026-10-24
.claude/rules/bundle-barrel-imports.mdWhat bundle-barrel-imports does
bundle-barrel-imports reviews package imports and favors paths to the modules you actually use. Instead of importing Button from @mui/material, it points to @mui/material/Button. The result is a smaller module graph for the import path.
The rule also covers optimizePackageImports in Next.js 13.5+, which keeps the shorter barrel syntax while rewriting imports during the build. Its examples include lucide-react, @mui/material, lodash, date-fns, and rxjs.
Tree-shaking cannot fix an external library on its own, because the bundler cannot optimize code it leaves outside the bundle. That makes direct imports relevant when a package is treated as external.
What it helps with
- spot imports that pass through barrel files
- switch re-exports to direct module paths
- reduce the number of modules loaded by an import
- configure package import optimization in Next.js
Example prompts for the agent
- Review this project and replace barrel-file imports with direct module paths.
- Find imports from
@mui/materialand suggest direct equivalents for the modules in use. - Check whether
optimizePackageImportsfits thelucide-reactsetup innext.config.js.
How to install bundle-barrel-imports
Manually: put the files in place
.claude/rules/bundle-barrel-imports.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/bundle-barrel-imports.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/bundle-barrel-imports.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/bundle-barrel-imports.mdManually: put the files in place
.clinerules/bundle-barrel-imports.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about bundle-barrel-imports
How do I install bundle-barrel-imports in Claude Code?
Add the rule at .claude/rules/bundle-barrel-imports.md.
What does bundle-barrel-imports do?
It guides Claude Code toward direct source-module imports instead of entry files that re-export many modules.
Why does tree-shaking not always remove the barrel-import cost?
An external library cannot be optimized by the bundler. Bundling it just to enable tree-shaking makes the full module graph take longer to analyze.
Source text
bundle-barrel-imports.md · MIT
---
title: Avoid Barrel File Imports
impact: CRITICAL
impactDescription: 200-800ms import cost, slow builds
tags: bundle, imports, tree-shaking, barrel-files, performance
---
## Avoid Barrel File Imports
Import 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'`).
Popular 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.
**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.
**Incorrect (imports entire library):**
```tsx
import { Check, X, Menu } from 'lucide-react'
// Loads 1,583 modules, takes ~2.8s extra in dev
// Runtime cost: 200-800ms on every cold start
import { Button, TextField } from '@mui/material'
// Loads 2,225 modules, takes ~4.2s extra in dev
```
**Correct (imports only what you need):**
```tsx
import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'
import Menu from 'lucide-react/dist/esm/icons/menu'
// Loads only 3 modules (~2KB vs ~1MB)
import Button from '@mui/material/Button'
import TextField from '@mui/material/TextField'
// Loads only what you use
```
**Alternative (Next.js 13.5+):**
```js
// next.config.js - use optimizePackageImports
module.exports = {
experimental: {
optimizePackageImports: ['lucide-react', '@mui/material']
}
}
// Then you can keep the ergonomic barrel imports:
import { Check, X, Menu } from 'lucide-react'
// Automatically transformed to direct imports at build time
```
Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
Libraries 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`.
Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
© tech-leads-club · MIT · tech-leads-club/agent-skills