I've seen more developers warn against barrel files because they can interfere with tree-shaking, increase build or test times, and sometimes contribute to circular dependencies. In my projects, though, I mainly use them as explicit public APIs for cohesive slices or domains. Code inside a slice never imports through its own barrel, while other slices can only access the exports exposed by that barrel. I may even enforce those rules with linting. This seems to reduce coupling and make each slice's boundary clear. The main alternative I can think of is splitting every slice into a separate package in a monorepo, but that feels too heavy and isn't practical for some projects. Are barrel files actually harmful in this use case, and what other approaches can enforce domain boundaries without adopting a monorepo?
5 Answers
A small, deliberate barrel used as a public API is very different from putting an index file in every directory and re-exporting everything. The latter is where many of the performance complaints come from. If each feature exposes only the symbols other features are meant to use, and internal code avoids importing through its own barrel, the pattern is usually reasonable. Modern bundlers can generally tree-shake named exports when modules have no unexpected side effects, though it’s still worth measuring your actual build.
You can enforce this without turning every slice into a package. Keep a public-api.ts or index.ts in each feature, export only the supported surface, and use lint rules or a dependency-graph tool to reject deep imports and forbidden cross-feature dependencies. A structure with explicit public and private areas can make the rule easy to understand: other modules may import from public, while private code remains inaccessible by convention and tooling.
Workspaces combined with package.json exports provide the strongest boundary: each package declares exactly which entry points are public, and consumers cannot import unlisted files. That can be worthwhile when the domains already have independent ownership or release concerns, but it is heavier than a feature-level barrel and requires maintaining several package manifests. For a single application, lint rules and a clear directory convention may offer most of the benefit with less overhead.
There isn’t a universal rule that barrel files are bad. They are useful when they represent an intentional API boundary, especially in libraries or well-defined features. They become counterproductive when they are added purely for shorter imports or automatically re-export every file. If the boundary is explicit, limited, documented, and checked by tooling, keeping the barrels is a defensible choice.
The tree-shaking issue depends on what the barrel and its modules do. Re-exporting unused, side-effect-free functions is usually handled well. Problems appear when importing the barrel evaluates modules with side effects, or when exported values perform work during initialization—for example, wrapping a value in a helper at module scope. Import order and circular re-exports can also make things confusing. Measure bundle output and build or test times before deciding that the pattern is a problem.
Path aliases can make the public imports readable, such as importing from @checkout rather than a long relative path. The lint configuration can then reject imports from @checkout/internal or other deep paths.