bundle-barrel-imports

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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+):

// 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

直接从源文件导入而非桶文件，避免加载数千个未使用的模块。桶文件是指重新导出多个模块的入口文件（例如，执行

export * from './module'

的

index.js

）。

热门图标和组件类库的入口文件中可能包含多达10000个重新导出项。对于许多React包来说，仅导入它们就需要200-800毫秒，这会同时影响开发速度和生产环境冷启动时间。

为什么Tree-shaking无法解决问题： 当类库被标记为外部依赖（不进行打包）时，打包工具无法对其进行优化。如果为了启用Tree-shaking而将其打包，构建过程会因分析整个模块图谱而大幅变慢。

错误示例（导入整个类库）：

tsx

import { Check, X, Menu } from 'lucide-react'
// 加载1583个模块，在开发环境中额外耗时约2.8秒
// 运行时成本：每次冷启动耗时200-800毫秒

import { Button, TextField } from '@mui/material'
// 加载2225个模块，在开发环境中额外耗时约4.2秒

正确示例（仅导入所需内容）：

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'
// 仅加载3个模块（约2KB对比约1MB）

import Button from '@mui/material/Button'
import TextField from '@mui/material/TextField'
// 仅加载你使用的内容

替代方案（Next.js 13.5+）：

// next.config.js - 使用optimizePackageImports
module.exports = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@mui/material']
  }
}

// 之后你可以保持便捷的桶文件导入方式：
import { Check, X, Menu } from 'lucide-react'
// 构建时会自动转换为直接导入

直接导入可使开发启动速度提升15-70%，构建速度提升28%，冷启动速度提升40%，并显著加快HMR（模块热替换）速度。

通常受影响的类库包括：

lucide-react

、

@mui/material

、

@mui/icons-material

、

@tabler/icons-react

、

react-icons

、

@headlessui/react

、

@radix-ui/react-*

、

lodash

、

ramda

、

date-fns

、

rxjs

、

react-use

。

参考链接：How we optimized package imports in Next.js