docs

Appearance

배럴 파일 임포트 피하기 ​

Overview ​

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').

Impact ​

  • Priority: CRITICAL
  • Performance: 200-800ms import cost, slow builds

Problem ​

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

Performance Improvements ​

Direct imports provide:

  • Dev boot: 15-70% faster
  • Builds: 28% faster
  • Cold starts: 40% faster
  • HMR: Significantly faster

Commonly Affected Libraries ​

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

Tags: bundle, imports, tree-shaking, barrel-files, performance