Leyman

Getting started ​

Install ​

sh
npm i -D barrelify
sh
pnpm add -D barrelify
sh
yarn add -D barrelify

TIP

Barrelify requires Node.js 24 or later. It installs two equivalent commands, barrelify and barrel.

Opt in an index file ​

Barrelify never creates files. Create the barrel yourself, starting with // AUTO-BARREL as its very first characters:

ts
// src/components/index.ts
// AUTO-BARREL

Any index.ts, index.tsx, index.cts or index.mts can be a barrel. Index files without the marker are left alone, so hand-written barrels can sit next to generated ones.

Generate barrels ​

sh
npx barrelify

Barrelify searches the current directory and everything below it for marked index files, and rewrites each one to re-export its sibling files, sorted by name:

src/components/
├── Button.tsx
├── button.styles.ts
├── types.d.ts
├── index.ts
└── icons/
    └── ...
ts
// AUTO-BARREL

export * from './Button.js';
export * from './button.styles.js';
  • Only .ts, .tsx, .cts and .mts files are exported. Declaration files (.d.ts) are skipped.
  • Subdirectories are not exported, unless you opt in.
  • Files ignored by .gitignore, and everything in node_modules, are skipped.
  • Which extensions are exported depends on the package's module system. See Module systems.

The marker is kept, so the next run rewrites the file again. Anything else you write in a barrel is replaced, except for type-only exports.

Commit the barrels, like any other source file.

Type-only exports ​

To re-export only the types of a file, change its line to export type *:

ts
// AUTO-BARREL

export * from './Button.js';
export type * from './button.styles.js';

Barrelify keeps the line type-only when it rewrites the file.

Subdirectories ​

To also re-export subdirectories, start the barrel with // AUTO-BARREL subdirectories. Each subdirectory that has its own index file is exported through it, sorted with the other files:

ts
// AUTO-BARREL subdirectories

export * from './Button.js';
export * from './button.styles.js';
export * from './icons/index.js';
  • Only direct subdirectories are exported, and only through their own index file. To export deeper ones, give icons/ a // AUTO-BARREL subdirectories barrel too.
  • The subdirectory's index file doesn't have to be a barrel, and its extension follows the same module system rules as sibling files.
  • Gitignored subdirectories and node_modules are skipped, and a line changed to export type * stays type-only.

Check barrels in CI ​

sh
npx barrelify --ci

--ci computes every barrel without writing, prints the barrels that would change, and exits with an error if any would. It is on by default when barrelify detects CI (with ci-info), so a plain barrelify in a CI script checks rather than writes.

Run barrelify before compiling, so the compiler sees up-to-date barrels. In an Nx workspace, a cached target per project does that, and checks instead of writing in CI:

json
// nx.json
{
    "targetDefaults": {
        "barrelify": {
            "executor": "nx:run-commands",
            "options": {
                "command": "barrelify",
                "cwd": "{projectRoot}"
            },
            "cache": true,
            "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/package.json"]
        }
    }
}

Next steps ​