Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/bundle-barrel-imports.md
Open on GitHub

What 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/material and suggest direct equivalents for the modules in use.
  • Check whether optimizePackageImports fits the lucide-react setup in next.config.js.

How to install bundle-barrel-imports

Manually: put the files in place

.claude/rules/bundle-barrel-imports.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
rendering-usetransition-loading rendering-usetransition-loading — a rule that swaps hand-rolled loading flags in React components for useTransition. Useful when a spinner runs on its own useState. CX Codex +1 ★ 7,191repo stars server-cache-react server-cache-react instructs the assistant to deduplicate server-side operations with React.cache() and prevent cache misses from inline object arguments. CX Codex +1 ★ 7,191repo stars architecture-avoid-boolean-props The architecture-avoid-boolean-props rule keeps component variants out of boolean props and moves them into composition. Use it when conditional UI branches start spreading across a component. CX Codex +1 ★ 7,191repo stars rendering-hydration-no-flicker rendering-hydration-no-flicker prevents server render failures and interface flickering when displaying content tied to browser storage. CX Codex +1 ★ 7,191repo stars patterns-explicit-variants patterns-explicit-variants — a rule that pushes one component per mode instead of a single component buried under boolean props. The call site then says what renders. CX Codex +1 ★ 7,191repo stars async-suspense-boundaries async-suspense-boundaries guides Claude Code to place data fetching behind Suspense boundaries so headers, sidebars, and layout shells render without blocking. CX Codex +1 ★ 7,191repo stars architecture-compound-components The architecture-compound-components rule describes splitting complex UI components into pieces that share state through context. It fits components that have accumulated render props and conditional options. CX Codex +1 ★ 7,191repo stars state-decouple-implementation state-decouple-implementation — a Claude Code rule that keeps state management inside providers and exposes only a context interface to UI components. Swap useState for Zustand or a server sync without touching a single UI file. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open