Back to Bundle Size Optimization
Avoid Barrel File Imports
bundleimportstree-shakingbarrel-filesperformance
Install this skill
npx skills add vercel-labs/agent-skillsWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
Barrel files serve as central export hubs, but they often force bundlers to process thousands of unnecessary modules. By importing directly from individual files, you bypass the massive overhead of parsing monolithic index files. This practice drastically shrinks bundle sizes and slashes startup times, especially in large React applications. When you import a single component or utility, you prevent the entire dependency tree from being loaded into memory. This optimization directly addresses slow hot module replacement (HMR), sluggish development server startups, and bloated production builds. While traditional tree-shaking attempts to remove unused code during the final build phase, direct imports solve the problem at the source. This improves IDE performance, reduces build-time memory consumption, and accelerates application initialization for end users across various modern web frameworks.
When to Use This Skill
- •Optimizing icons libraries like lucide-react or react-icons in React projects
- •Reducing load times for heavy UI component frameworks like MUI or Headless UI
- •Trimming large utility libraries such as lodash or ramda to only necessary functions
- •Speeding up application boot time in Next.js projects lacking optimizePackageImports
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “refactor my imports to avoid barrel files
- “how do I make my build faster by fixing index imports
- “optimize my react project bundle size by removing barrel files
- “convert my library imports to direct file paths
- “speed up my dev server start time by changing how I import components
What this skill does
- •Replaces recursive barrel imports with granular file-path imports
- •Reduces total module graph size during development and production
- •Shortens cold start times for applications utilizing large libraries
- •Improves HMR speed by minimizing dependency analysis
- •Prevents accidental inclusion of massive library dependency trees
When not to use it
- ✕When using build tools that perform automatic transformation of barrel imports
- ✕In small projects where build performance is not a bottleneck
- ✕If your library is specifically architected to support tree-shaking through side-effect-free packages
Example workflow
- Identify slow-loading libraries in your project using a bundle visualizer
- Scan the codebase for deep-indexed import statements from large libraries
- Replace barrel import statements with specific path imports pointing to the individual files
- Verify the application still renders correctly after the refactor
- Re-run build or dev server to measure the performance improvement in startup time
Prerequisites
- –Bundle analysis tool
- –Knowledge of your library's internal directory structure
Pitfalls & limitations
- !Direct paths may change if the library author updates their internal structure
- !Requires manual maintenance if the project grows significantly
- !Reduces code readability compared to standard import syntax
FAQ
Why doesn't tree-shaking solve this automatically?
Tree-shaking only removes unused code during the final build. It does not prevent the overhead of parsing and analyzing the huge module graph that barrel files create during development.
Does this work for all libraries?
It depends on whether the library exports its internal files in a way accessible to your bundler. Most major UI libraries support this pattern, but private packages might hide their internal files.
Is there a way to keep my code clean without manual direct imports?
Yes. If you are using Next.js 13.5 or later, you can configure the optimizePackageImports setting in your next.config.js to perform this transformation automatically.
How it compares
Generic prompts often suggest standard tree-shaking, whereas this skill forces a structural refactor to the import graph to bypass bundler bottlenecks entirely.
📄 Full skill instructions — original source: vercel-labs/agent-skills
## 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.,
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):**
**Correct (imports only what you need):**
**Alternative (Next.js 13.5+):**
Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
Libraries commonly affected:
Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
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):**
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):**
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+):**
// 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 timeDirect 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)
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/bundle-barrel-imports/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/vercel-labs/agent-skills/bundle-barrel-imports/SKILL.md - Cursor:
~/.cursor/skills/vercel-labs/agent-skills/bundle-barrel-imports/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/vercel-labs/agent-skills/bundle-barrel-imports/SKILL.md
🚀 Install with CLI:npx skills add vercel-labs/agent-skills
Recommended Rules
View more rules →⚡ Performance Optimization Agent - Speed Expert
Agentic AIPerformanceOptimization
You are an expert performance optimization agent specialized in identifying and fixing performance bottlenecks. Apply systematic reasoning to measure,...
Web Performance Optimization Expert
PerformanceWeb VitalsOptimization
You are an expert in web performance optimization and Core Web Vitals. Key Principles: - Optimize for Core Web Vitals - Minimize Time to First Byte (...
Next.js Performance Optimization
Next.jsPerformanceOptimization
You are an expert in Next.js performance optimization. Key Principles: - Optimize images and fonts - Minimize client-side JavaScript - Use proper cac...
Recommended Workflows
View more workflows →Reduce Bundle Size
PerformanceBundleOptimization
--- description: Analyze and reduce JS bundle --- 1. **Analyze Bundle**: // turbo - Run `npm install @next/bundle-analyzer` // turbo - Ru...
Analyze Bundle Size
PerformanceNext.jsOptimization
--- description: Visualize and reduce your production build size --- 1. **Install Analyzer**: - Install the Next.js bundle analyzer. // turbo ...
React Performance Profiling
ReactPerformanceDebugging
--- description: Identify slow components using React Profiler --- 1. **Install DevTools**: - Install React Developer Tools extension for Chrome/F...