🚫 No Barrel File

Eliminate barrel file imports to boost tree-shaking, reduce bundle size, and speed up test performance.

No Barrel File is a CLI tool and GitHub Action that detects imports from barrel files (files that just re-export other modules) and automatically replaces them with direct file paths.

---

🧐 Why?

Barrel files (index.ts exporting everything) are convenient but costly.

1. Tree-Shaking Failures: Tools like Webpack and Rollup often struggle to tree-shake barrel files effectively, including dead code in your bundle.
2. Slow Tests: In Jest/Vitest, importing one named export from a barrel file often loads every exported module in that barrel, significantly slowing down startup time.
3. Circular Dependencies: Barrel files are the #1 cause of "Module undefined" circular dependency errors.

The Transformation

Before (Imports everything in ./utils):

import { formatDate } from './utils';

After (Imports only what is needed):

import { formatDate } from './utils/date-formatter';

---

🚀 GitHub Action (Recommended)

You can run this tool automatically in your CI/CD pipeline to detect or fix barrel imports.

1. Auto-Fix Workflow (Best for lazy maintenance)

Create a workflow .github/workflows/fix-barrels.yml to automatically fix imports and commit the changes to your PRs.

name: Auto-Fix Barrel Files
on: [pull_request]

permissions:
  contents: write # Required to commit changes

jobs:
  fix-imports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run No Barrel File
        uses: chintan9/no-barrel-file@v1
        with:
          mode: 'replace'
          alias-config-path: 'tsconfig.json' # Required for 'replace' mode
          extensions: '.ts,.tsx'
      
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "refactor: resolve barrel file imports"

2. Check-Only Workflow (Best for strict enforcement)

Fail the build if developers use barrel imports.

steps:
  - uses: actions/checkout@v4
  
  - name: Check for barrel files
    uses: chintan9/no-barrel-file@v1
    with:
      mode: 'display' # Will list files but not modify them

Action Inputs

Input	Description	Default	Required?
mode	Operation mode: count, display, or replace	display	No
alias-config-path	Path to tsconfig.json (Required for resolving paths in replace mode)	-	Yes (for replace)
root-path	Root directory of the project	.	No
extensions	File extensions to scan	.ts,.js,.tsx,.jsx	No
ignore-paths	Comma-separated list of folders to ignore	-	No

---

💻 CLI Usage

You can also use the tool locally via your terminal.

Installation

# Install globally
npm install -g no-barrel-file

# Or run via npx
npx no-barrel-file --help

Commands

1. Display Barrel Files

Lists all files in your project that are acting as barrel files (index files exporting other modules).

npx no-barrel-file display

2. Replace Imports (The Magic ✨)

Automatically rewrites imports in your code to point directly to the source file instead of the barrel file.

Note: This requires your tsconfig.json to resolve paths correctly.

npx no-barrel-file replace --alias-config-path tsconfig.json

3. Count

Just returns the number of barrel files found (useful for scripts).

npx no-barrel-file count

CLI Options

Flag	Alias	Description	Default
--root-path	-r	Root path of the project	Current Directory
--extensions	-e	File extensions to process	.ts,.js,.tsx,.jsx
--ignore-paths	-i	Comma-separated paths to ignore	-
--gitignore-path	-g	Path to .gitignore file	.gitignore
--alias-config-path	-a	Path to tsconfig.json (Replace mode only)	-

---

🛠️ Configuration & ignoring files

No Barrel File automatically respects your .gitignore file.

If you want to ignore specific folders manually (like legacy code or tests), use the --ignore-paths flag:

npx no-barrel-file display --ignore-paths "src/legacy,src/__tests__"

---

🤝 Contributing

Contributions are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

_{Built with ❤️ by chintan9}