Barrel files and circular imports: what index.ts does to 52 TypeScript repos
TL;DR A barrel file is an index.ts that re-exports other files, so code can import a whole folder from one path. In 17 of 52 TypeScript repos with 1,000+ GitHub stars (33%), the most-imported production file is an inde
TL;DR
- A barrel file is an
index.tsthat re-exports other files, so code can import a whole folder from one path. - In 17 of 52 TypeScript repos with 1,000+ GitHub stars (33%), the most-imported production file is an index file, and in 15 of them it is a barrel or partly one.
- In six TypeScript repos indexed for this post, every barrel that sat in a runtime import cycle was imported from inside its own package or app.
- In pi, pointing one import at the defining files instead of the barrel cut madge's runtime cycle count from 6 to 3.
Numbers come from repowise's index of 195 public repos with 1,000+ GitHub stars (November 2026), 52 of them TypeScript, plus six fresh local indexes.
A barrel file is an index.ts whose job is to re-export other files, so the rest of the code can write import { Button } from "./components" instead of reaching into ./components/Button/Button. All six TypeScript repos I indexed for this post have index files, from 3 in repomix to 182 in openstatus. I wanted to know how central they really are in popular repos, and how often they sit inside circular import chains, so I measured both.
How often is the most-imported file a barrel?
I looked at the 52 TypeScript repos in a set of 195 public repositories with 1,000+ GitHub stars, and at each repo's hub: the production file imported by the most other production files (tests, generated and vendored code excluded).
- In 17 of 52 repos (33%), the hub is a file named
index.ts,index.tsxor similar. - Across each repo's five most-imported files (260 slots), 49 are index files (19%), and 21 of the 52 repos have at least one in their top five.
A filename is only a proxy, since an index.ts can hold real code. So I downloaded all 49 of those files from GitHub at the commit each repo was indexed at and looked at what they contain:
| What the index file contains | Top hub (17) | Top-five slots (49) |
|---|---|---|
Mostly re-exports (export ... from) |
12 | 39 |
| Re-exports plus its own code | 3 | 6 |
| Ordinary module that happens to be named index | 2 | 4 |
So in 15 of 52 popular TypeScript repos, the single most-imported file is a barrel or partly one. Grafana's @grafana/data entry is the best-known case, and I went through it in the post on hub files.
That is the first thing barrels do to a codebase. They become the hub. Every file that imports a package through its barrel depends, on paper, on everything that barrel re-exports.
Why do people use barrel files?
There are two good reasons, and they are different.
A package's public API. When code outside a package imports it, the barrel is the contract: import { dateTime } from "@grafana/data" keeps working when the package moves dateTime to another file. This is what main and exports in package.json point at.
Nice import paths inside one project. import { Button, Card } from "@/components" reads better than two deep paths. This one is mostly cosmetic, and it is where the costs below come from.
What do barrel files cost?
Loading. Importing one name from a barrel means loading the barrel, and the barrel imports every file it re-exports. Under ES module rules each of those modules is evaluated, and each of their imports too. Vite's performance guide says it directly: importing one API from a barrel means every file in it has to be fetched and transformed, so it recommends importing the individual file. A bundler can skip modules whose exports you never use only when it knows they have no side effects, which is what "sideEffects": false in package.json tells webpack and other bundlers. A test runner that executes modules one by one, like Jest or Vitest, loads whatever the import graph says.
Hidden unused exports. When a barrel is a package entry point, unused-export tools treat everything it re-exports as public API and stay quiet about it by default (Knip has --include-entry-exports to audit that surface). I covered that in the post on unused exports in the same 52 repos.
Circular import chains. A file inside a folder imports the folder's own barrel to get a sibling. The barrel re-exports that file too. Now the file depends on itself through the barrel, and every other file the barrel touches joins the chain. This is the one I measured.
Do barrel files cause circular imports?
The dataset has cycle counts per repo, but not which files are in each cycle. So I indexed six TypeScript repos locally and looked at every circular import group, meaning a set of two or more files that can all reach each other through imports. I counted two ways: all imports, and runtime imports only, dropping import type edges that TypeScript erases at compile time.
| Repo (commit) | Production JS/TS files | Cycle groups, all imports | Cycle groups, runtime | Runtime groups with an index file | Files in runtime cycles | ...of them index files |
|---|---|---|---|---|---|---|
grafana/grafana (12c49a4d) |
6,486 | 68 | 26 | 1 | 950 | 5 |
openstatusHQ/openstatus (bba13dd) |
2,415 | 17 | 5 | 2 | 53 | 13 |
earendil-works/pi (555e975) |
1,674 | 29 | 7 | 3 | 34 | 5 |
shadcn-ui/ui (8ab2771) |
3,864 | 10 | 6 | 0 | 25 | 0 |
effector/effector (7d69926) |
240 | 3 | 2 | 0 | 6 | 0 |
yamadashy/repomix (758c3d71) |
222 | 2 | 1 | 0 | 12 | 0 |
Three things stood out.
-
Type-only imports make up a lot of the cycles. Grafana goes from 1,837 files in cycles to 950 once
import typeedges are dropped, and pi from 244 to 34. Those chains disappear from the compiled JavaScript. -
Package-level barrels were in no cycle at all. Grafana's
grafana-dataandgrafana-uiindex files are the two most-imported files in the repo, and neither is inside any circular group. Code outside a package that imports the package's front door cannot loop back through it unless the package imports its consumers. -
The barrels that do sit in cycles are imported from inside their own package. In 3 of the 6 repos, a barrel was part of a runtime cycle. I checked who imports each of those 23 index files from inside its cycle, and every importer lives in the same package or app as the barrel, usually in a sibling folder. Not one of them is a different package coming in through the front door. In pi, even the
coding-agentpackage entry is in a cycle, because a file inside the package imports it.
To see how much of each cycle the barrels were responsible for, I re-pointed every import of an index file at the file that actually defines each imported name (following re-exports through nested index files) and recomputed the groups. In openstatus, whose Drizzle schema files import each other through folder index files, the largest runtime group went from 42 files to 18. 16 of those 18 are table files whose relations reference each other in both directions, a real two-way dependency. The other 24 (11 index files, the 11 validation modules they re-export, and two more re-exported files) were in the group only because imports went through the barrels. In pi, one 6-file group disappeared completely. In grafana, shadcn-ui, effector and repomix nothing changed, because their cycles do not go through barrels.
One cycle, before and after
The group that disappeared in pi is a clean example. pi's chord package gives each folder an index.ts that is its public surface. host/index.ts is 34 lines of re-exports:
// packages/chord/src/host/index.ts (excerpt)
export type { Ctx } from "./ctx.ts";
export { defineFacet, type Facet, type FacetHost, type FacetSelf, type ServeOptions } from "./facet.ts";
export {
type CommittedReload,
createHost,
...
} from "./host.ts";
export { sleep, untilAborted } from "./sleep.ts";
jobs/job.ts needs two things from that folder, the Ctx type and the sleep function, and gets them from the barrel:
import { type Ctx, sleep } from "../host/index.ts";
I copied packages/chord/src out of the repo and ran madge with type imports skipped, so it only reports chains that exist in the emitted JavaScript. The setting goes in a .madgerc in the folder you run madge from:
{"detectiveOptions":{"ts":{"skipTypeImports":true},"tsx":{"skipTypeImports":true}}}
$ npx madge --circular --extensions ts chord-src
Processed 297 files (5.1s) (5 warnings)
✖ Found 6 circular dependencies!
1) delta/diff.ts > delta/index.ts
2) delta/index.ts > delta/tracker.ts
3) host/attempt.ts > jobs/internal.ts > jobs/job.ts > host/index.ts > host/host.ts
4) host/attempt.ts > jobs/internal.ts > jobs/job.ts > host/index.ts > host/host.ts > host/object.ts
5) jobs/internal.ts > jobs/job.ts > host/index.ts > host/host.ts > host/object.ts
6) remote/hold.ts > remote/relay.ts
Cycles 3 to 5 all run through job.ts > host/index.ts. job.ts wants sleep, but importing the barrel also imports host.ts, which reaches object.ts, which imports the jobs module, which imports job.ts. The fix is one line, pointing each import at the file that defines it:
-import { type Ctx, sleep } from "../host/index.ts";
+import type { Ctx } from "../host/ctx.ts";
+import { sleep } from "../host/sleep.ts";
$ npx madge --circular --extensions ts chord-src-after
Processed 297 files (3.9s) (5 warnings)
✖ Found 3 circular dependencies!
1) delta/diff.ts > delta/index.ts
2) delta/index.ts > delta/tracker.ts
3) remote/hold.ts > remote/relay.ts
Three chains gone, nothing else touched. The loading cost shows up in the same graph. From madge's JSON output, host/index.ts reaches 150 of the 297 files in the package at runtime. host/sleep.ts reaches none, since its only import is a type. Before the change, job.ts pulled in half the package to call sleep.
The two delta/ cycles that are left are a different shape: delta/index.ts defines helpers like overlap itself and also re-exports diff.ts, which imports those helpers back from the index. Rewriting an import does not help there, because the code lives in the barrel. Moving the shared helpers into their own file (say delta/core.ts) that both import is the fix for that one.
None of these chains is a bug on its own. ES modules handle cycles as long as nothing reads a binding before its module has finished evaluating. They do mean that loading any file in the chain loads all of them, and that the order modules run in depends on which one gets imported first.
When is a barrel file fine?
From what I saw in these repos, the barrel at the edge of a package is the healthy case. The grafana-data package from the table above sets "sideEffects": false and uses exports to expose ., ./unstable and ./internal. shadcn's CLI package does something similar with one subpath per area:
"exports": {
".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
"./registry": { ... },
"./schema": { ... },
"./utils": { ... },
"./icons": { ... },
"./preset": { ... },
"./tailwind.css": "./dist/tailwind.css"
}
with "sideEffects": ["./dist/tailwind.css"], which lists the one file that really does have side effects. A consumer that only needs the schema imports shadcn/schema and never loads the rest. The shadcn-ui/ui architecture view shows those packages and the edges between them.
Fixes that worked
1. Inside a package, import the file that defines the name. Keep the barrel for consumers outside. This is the one-line fix above, and editors will autocomplete the direct path if you let them.
2. Enforce it with no-restricted-imports. ESLint 9's pattern regex option can block relative imports of an index file:
// eslint.config.mjs
"no-restricted-imports": ["error", {
patterns: [{
regex: "^\\.\\.?/(.+/)?index(\\.[jt]sx?)?$",
message: "Import the file that defines it, not the folder index.",
}],
}],
On pi's job.ts it flags every barrel import, including the one that closed the cycle:
7:1 error '../context/index.ts' import is restricted from being used by a pattern. Import the file that defines it, not the folder index no-restricted-imports
...
12:1 error '../host/index.ts' import is restricted from being used by a pattern. Import the file that defines it, not the folder index no-restricted-imports
pi uses folder index files as deliberate module boundaries, so on that codebase the rule would be a design change, not a cleanup. On a project where barrels exist for short paths, it is a good default. A regex cannot tell a bare folder import (from "../monitors") from a file import, so for those a cycle check in CI (madge --circular, or dependency-cruiser's no-circular rule) catches what the lint rule misses.
3. Mark packages side-effect free. "sideEffects": false, or a list of the files that do have side effects, lets bundlers drop re-exported modules you never use. List CSS imports and polyfills, or they get dropped too.
4. Use exports subpaths for big packages. One entry per area (./schema, ./utils) gives consumers small barrels instead of one huge one.
5. Move code out of barrels. An index that defines helpers and re-exports files that use those helpers is a cycle by construction, as in pi's delta/.
For a wider look at the tools that draw these graphs (madge, dependency-cruiser, Nx, esbuild's metafile), this guide to JavaScript and TypeScript dependency graphs has the commands and output for each. Cycles in a language whose compiler forbids them look very different, which is what the Go post in this series is about.
If your team removed barrels from inside a package, did you keep a barrel at the package entry, or drop them everywhere?
How I got these numbers
The cohort is 195 of the most-starred public repositories indexed on repowise (1,000+ GitHub stars each, 253,688 production source files, November 2026), 52 of them with TypeScript as GitHub's primary language. Hub figures come from each repo's stored import graph at its latest index (May to November 2026); the hub files section of the code health report has the cohort-wide numbers. "Index file" means a basename of index with a JS or TS extension, or mod.ts. I classified the 49 index files in top-five slots by reading each one at its indexed commit: "mostly re-exports" means at least half of its top-level statements are export ... from. The six local runs used repowise init --yes --no-prose --no-editor-setup (repowise 0.60.1) on fresh clones at the commits in the table, then a strongly connected components pass over production JS and TS files (classified by repowise's code-origin rules). The local file counts cover only JS and TS, so Grafana's 6,486 is lower than its production file count across all languages. The "re-point at the defining file" pass follows export ... from chains name by name and leaves any name it cannot trace on the index file. The before/after used madge 8.0.0, ESLint 9.39.5 and typescript-eslint 8.72.2 on Node 22.19, on a copy of pi's packages/chord/src at 555e975.
FAQ
What does barrel file mean?
A barrel file is a module, usually index.ts or index.js, whose job is to re-export other files from its folder. Code can then write import { Button } from "./components" instead of importing each file by its full path.
Do barrel files break tree shaking?
They can. A bundler can drop the re-exported modules you never use only when it knows they have no side effects, which is what "sideEffects": false (or a list of the files that do have side effects) in package.json tells it. Test runners that execute modules one by one, like Jest or Vitest, load everything the barrel imports.
Is there an ESLint rule for barrel files?
ESLint's built-in no-restricted-imports can block relative imports of a folder index with a regex pattern, as shown above. It cannot tell a bare folder import from a file import, so pair it with a cycle check in CI such as madge --circular or dependency-cruiser's no-circular rule.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.