barrel-unbundler 🎯

Convert barrel imports (index.ts) to direct imports for better tree-shaking and faster builds.

Why?

Barrel files (index.ts) are convenient for organizing exports, but they can cause issues:

• Poor tree-shaking: Bundlers may include unused exports
• Slower builds: More files to parse and analyze
• Circular dependencies: Barrel files can create complex dependency graphs

This tool automatically converts:

// Before: barrel import
import { Button, Input, helper } from './components';

// After: direct imports
import { Button } from './components/Button';
import { Input } from './components/Input';
import { helper } from './components/utils';

Installation

npm install -g barrel-unbundler
# or
npx barrel-unbundler

Usage

CLI

# Convert all files in current directory
barrel-unbundler

# Dry run (preview changes)
barrel-unbundler --dry-run

# Verbose output
barrel-unbundler --verbose

# Specify file types
barrel-unbundler --type ts tsx vue

# Custom tsconfig path
barrel-unbundler --tsconfig ./tsconfig.app.json

# Exclude patterns
barrel-unbundler --exclude __tests__ __mocks__

Options

Option	Description	Default
-d, --dry-run	Preview changes without modifying files	false
-v, --verbose	Show detailed logs	false
-t, --type <types...>	File types to process	ts tsx js jsx vue
-c, --tsconfig <path>	Path to tsconfig.json	tsconfig.json
-e, --exclude <patterns...>	Patterns to exclude	[]

Programmatic API

import { unbundle } from 'barrel-unbundler';

const result = await unbundle({
  rootDir: './src',
  dryRun: true,
  verbose: false,
  fileTypes: ['ts', 'tsx', 'vue'],
  tsconfigPath: './tsconfig.json',
  exclude: ['__tests__'],
});

console.log(`Converted ${result.totalConverted} files`);
console.log(`Total imports converted: ${result.totalImports}`);

Features

✅ Supported File Types

• TypeScript (.ts)
• TSX (.tsx)
• JavaScript (.js)
• JSX (.jsx)
• Vue (.vue) - both <script> and <script setup>

✅ Smart Detection

• Reads tsconfig.json for path aliases
• Analyzes barrel files to map exports to source files
• Preserves type-only imports
• Handles default exports correctly
• Supports namespace imports (import * as)

✅ Safe Transformations

• Dry-run mode to preview changes
• Preserves non-barrel imports
• Handles mixed imports (some from barrel, some direct)
• Maintains code formatting

How It Works

1. Analyze tsconfig.json: Reads path aliases from compilerOptions.paths
2. Find barrel files: Locates all index.ts files in the project
3. Build export mapping: Analyzes each barrel file to map export names to source files
4. Transform imports: Converts barrel imports to direct imports in target files

Examples

TypeScript

// Before
import { useState, useEffect } from './hooks';
import type { User, Post } from './types';

// After
import { useState } from './hooks/useState';
import { useEffect } from './hooks/useEffect';
import type { User } from './types/User';
import type { Post } from './types/Post';

Vue

<script setup lang="ts">
// Before
import { Button, Input } from '@/components';

// After
import Button from '@/components/Button/Button.vue';
import Input from '@/components/Input/Input.vue';
</script>

TSX/React

// Before
import { Header, Footer, Sidebar } from './layout';

// After
import { Header } from './layout/Header';
import { Footer } from './layout/Footer';
import { Sidebar } from './layout/Sidebar';

Configuration

Path Aliases

The tool automatically reads path aliases from tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

Excluding Files

Use the --exclude option to skip certain patterns:

barrel-unbundler --exclude __tests__ __mocks__ stories

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

sugitat