BitlystBitlyst
PostsSeriesTopicsAbout

Bitlyst

Short, diagram-first posts on JavaScript, React & Next.js. Follow via RSS or the newsletter.

© 2026 Mohsen Fallahnejad

PostsSeriesTopicsLinksAboutSync devicesRSSGitHubX
Posts/typescript
AI-generated illustration. One import from a shelf still makes the bundler read every book on it.
Intermediate5 min read

Part 1 of Common Mistakes

Barrel Files (`index.ts`): Why One Import Can Slow Your Build

A barrel re-exports a whole folder. Tree shaking may still drop unused code, but the bundler often walks every file behind that index first.

Mohsen Fallahnejad

Mohsen Fallahnejad

Nov 16, 2026Discuss

You add a tidy folder: ten components, one index.ts that re-exports them all, and a single import line in the app:

ts
import { Button } from "@/components/ui";

You only wanted Button. The dev build still feels heavier than it should.

The mental model: the whole shelf#

A barrel file is an index.ts that re-exports a folder so you can import from one path. It's convenient. It's also like asking the library for one book and having the librarian pull every book on that shelf into the room before they hand you the right one.

The bundler's job is to follow every export * from and export { X } from while it figures out what your entry file actually needs. Tree shaking can still drop unused code from the final bundle. The work of reading and linking the rest of the shelf often happens anyway.

AI-generated illustration. One index card fans out to many modules behind it.AI-generated illustration. One index card fans out to many modules behind it.

How it works#

A typical barrel:

ts
// components/ui/index.ts
export * from "./button";
export * from "./dialog";
export * from "./data-table";

Each file may import heavy packages:

ts
// data-table.ts
import { LineChart } from "recharts";
export function DataTable() { /* ... */ }

Your page only imports Button:

ts
import { Button } from "@/components/ui";

Modern bundlers (esbuild, Rollup, Turbopack, webpack) can leave DataTable and recharts out of the shipped JavaScript if nothing references them. The catch is what they must walk to be sure.

I measured a tiny demo on my machine with esbuild 0.25, three modules behind one barrel (lodash/get, date-fns/format, recharts), and one entry file that imports only pickA from the barrel:

Import pathModules esbuild had to readMinified bundleesbuild time
./direct/a (no barrel)548.4 KB5 ms
./barrel (re-export all)4718.4 KB43 ms

Same shipped size. About eight times more files parsed, and about eight times longer to bundle that one entry, because the barrel pulled the resolver through every re-exported file and its dependencies.

That gap is what you feel in a big app: slower first compile, slower HMR, TypeScript and ESLint spending time on modules you never imported at runtime, and CI builds that redo the same graph on every push.

Barrels hurt more when:

  • Side effects at the top of a re-exported file (import "./polyfill") force those modules to stay in the bundle even if you never call them.
  • Libraries ship their own barrels (@mui/material, some icon packs) so deep imports are the documented fix.
  • Monorepos nest barrels (packages/ui/index.ts → ten more index.ts files) and multiply the graph.

In practice#

Keep barrels for public package APIs you publish to npm. Inside an app, prefer direct imports on hot paths:

ts
// before
import { Button } from "@/components/ui";

// after
import { Button } from "@/components/ui/button";

If you like the short path, use a subpath in package.json ("exports") instead of a giant export * file. Your editor and bundler then resolve one file, not a fan-out.

Run your own check when a folder grows past a handful of files: build one route with the barrel import and again with a direct import, compare the bundler's module count or build time. You don't need a guess. The shelf either shows up in the stats or it doesn't.

Honest stakes: on a ten-file hobby project, you may never notice. On a design-system folder imported from hundreds of routes, barrels are a common reason cold next dev and CI builds feel slower than the code changed.

Say it in an interview: A barrel file re-exports a folder from one index.ts so imports look clean. Tree shaking can still drop unused exports from the final bundle, but the bundler usually has to parse and analyze every re-exported module first. That's extra build work and can pull in side effects. I reach for direct imports or package exports maps on hot paths, and keep barrels for library public APIs.

Cheat sheet#

What you writeWhat often happens
import { Button } from "./ui" via index.tsResolver walks every file the barrel re-exports
Same runtime bundle as direct importOften yes, when tree shaking works
Same build cost as direct importOften no: more files parsed and typed
export * + side-effect importsUnused modules can still ship
Fix on hot pathsImport the file directly or use exports subpaths

Advanced · optional

Going deeper#

Everything above is enough to explain this in an interview. This part is for the curious: full numbers, edge cases and what's still unproven.

How I measured the table#

Fresh temp project with lodash, date-fns, and recharts in node_modules. Three small modules, each importing one of those packages. One barrel/index.ts with export * from each module.

Two entry files, both only calling pickA():

  • entry-direct.ts → import { pickA } from "./direct/a"
  • entry-barrel.ts → import { pickA } from "./barrel"

esbuild 0.25 on an Apple Silicon Mac, --bundle --platform=browser --minify, with --metafile for input counts. Times are single runs (not medians); the ratio stayed stable across repeats.

When the bundle does grow#

If any re-exported file runs code at import time, tree shaking cannot drop it:

ts
// dialog.ts
import "./focus-trap-polyfill"; // runs on import
export function Dialog() { /* ... */ }

Importing anything from the barrel can drag that polyfill into the client bundle even if you never open a dialog.

TypeScript and the editor#

Barrels also widen the type graph: opening a file that imports @/components/ui can make the language service load types for every re-export behind the index. That shows up as slower autocomplete and higher memory in large repos, separate from bundler time.

Further reading#

  • TypeScript performance wiki — barrel files
  • Package "exports" field for clean entry points without export * soup
Filed under#typescript#bundler#performance#barrel-files#tree-shaking

Series

Common Mistakes

Patterns that look fine in code review until production, the bundler, or an interview question proves otherwise.

  1. 1Barrel Files (`index.ts`): Why One Import Can Slow Your Build · you are here
  2. 2The useEffect that only derived state · coming soon
  3. 3The forEach that did not wait for await · coming soon
  4. 4The secret that NEXT_PUBLIC_ copied into git · coming soon

New parts land here first — subscribe below to get them in your inbox.

Was this worth your time?

One tap tells me what to write more of.

Mohsen Fallahnejad

Written by

Mohsen Fallahnejad

Frontend engineer explaining JavaScript, React & Next.js internals in posts you can finish over coffee. More about me

X ↗GitHub ↗LinkedIn ↗
← OlderHoisting and the TDZ: Why let Throws and var Is undefined

Start the discussion

Questions, corrections, a better approach? I read and reply to every comment.

Read next

What Is Turbopack? How Next.js's Rust Bundler Avoids Doing Work Twice

Turbopack is the Rust bundler inside Next.js. Learn the one idea behind its speed, remembering every small step, and when you'll actually feel it.

Nov 10, 20265 min read

Are TypeScript Enums a Good Idea? (Bundle Size & Runtime)

A practical guide to TypeScript enums, their runtime cost, and better alternatives for modern frontend apps.

Dec 30, 20253 min read

React Server Components vs 'use client': What Actually Ships to the Browser

Server Components send the result; Client Components send the result plus the code. What 'use client' really does, why it doesn't mean browser-only, and where to put it.

Nov 13, 20267 min read

Get new posts in your inbox

One email when a new post is out: short, diagram-first explanations of JavaScript, React and Next.js. No spam, unsubscribe any time.

5 min left
Discuss👍 React
👍