barrels

Tools for creating barrel files.

Features

This library exposes a set of utility functions which:

• Collect files and directories
• Extract export declarations from files using the Oxidation Compiler toolchain
  • Supports all export declaration types
  • Supports detecting type declarations
  • Supports detection and handling of external dependencies and built-ins
  • Supports various tsconfig settings: paths, references, moduleResolution, allowImportingTsExtensions
  • Supports monorepo setups
• Handle file extensions
  • Manually remove or remap extensions
  • Automatic handling by considering tsconfig settings
• Convert sources to export/import declarations
• CLI
  • Create barrels via a classic config file (barrels.config.*)
  • Queue-based watch mode to keep things up to date
  • Config hot-reloading in watch mode
  • Gitignore integration
  • Infinite loop prevention when barrel files are modified
  • Pretty output with bordered visualization of generated barrel contents

Installation

npm

npm install -D @monstermann/barrels

pnpm

pnpm add -D @monstermann/barrels

yarn

yarn add -D @monstermann/barrels

bun

bun add -D @monstermann/barrels

Setup

barrels.config.ts

import { defineConfig } from "@monstermann/barrels";

export default defineConfig([
    () => {
        // See API/Guide for how to create barrel files,
        // or use one of the presets further below!
    },
]);

Usage

npm

npx barrels
npx barrels --watch
npx barrels --help

pnpm

pnpm exec barrels
pnpm exec barrels --watch
pnpm exec barrels --help

yarn

yarn barrels
yarn barrels --watch
yarn barrels --help

bun

bun run barrels
bun run barrels --watch
bun run barrels --help

barrels-flat

This preset collects files and creates classic flat barrels, for example:

export * from "./foo";
export * from "./bar";

Installation

npm

npm install -D @monstermann/barrels-flat

pnpm

pnpm add -D @monstermann/barrels-flat

yarn

yarn add -D @monstermann/barrels-flat

bun

bun add -D @monstermann/barrels-flat

Setup

barrels.config.ts

import { defineConfig } from "@monstermann/barrels";
import { flat } from "@monstermann/barrels-flat";

export default defineConfig([
    flat(options)
]);

Options

interface FlatBarrelConfig {
    // Glob(s) to directories to create barrel files in.
    // Default: process.cwd()
    entries?: string | string[];
    // Glob(s) to collect files, relative to each entry.
    // Default: *.ts
    include?:
        | string
        | string[]
        | ((ctx: { entry: string; outDir: string }) => string | string[]);
    // Glob(s) or RegExp(s) to exclude matched files.
    // Default: undefined
    exclude?: string | string[] | RegExp | RegExp[];
    // The directory where the barrel files should be created.
    // Will be resolved against the current entry.
    // Default: entry
    outDir?: string | ((ctx: { entry: string }) => string);
    // The file name used to create the barrel file within `outDir`.
    // Default: index.ts
    outFile?: string | ((ctx: { entry: string; outDir: string }) => string);
}

barrels-namespace

This preset collects files and creates TypeScript namespace barrels, for example:

example.d.ts

import { foo } from "./foo.js";
import { bar } from "./bar.js";

declare namespace Example {
    export { foo, bar };
}

export { Example };

example.js

import { foo } from "./foo.js";
import { bar } from "./bar.js";

export const Example = {
    foo,
    bar,
};

Installation

npm

npm install -D @monstermann/barrels-namespace

pnpm

pnpm add -D @monstermann/barrels-namespace

yarn

yarn add -D @monstermann/barrels-namespace

bun

bun add -D @monstermann/barrels-namespace

Setup

barrels.config.ts

import { defineConfig } from "@monstermann/barrels";
import { namespace } from "@monstermann/barrels-namespace";

export default defineConfig([
    namespace(options)
]);

Options

interface NamespaceBarrelConfig {
    // Glob(s) to directories to create barrel files in.
    // Default: process.cwd()
    entries?: string | string[];
    // Glob(s) to collect files, relative to each entry.
    // Default: *.ts
    include?:
        | string
        | string[]
        | ((ctx: {
              entry: string;
              outDir: string;
              title: string;
          }) => string | string[]);
    // Glob(s) or RegExp(s) to exclude matched files.
    // Default: undefined
    exclude?: string | string[] | RegExp | RegExp[];
    // The title of the namespace.
    // Default: Path.basename(entry)
    title?: string | ((ctx: { entry: string }) => string);
    // The directory where the barrel files should be created.
    // Will be resolved against the current entry.
    // Default: entry
    outDir?: string | ((ctx: { entry: string; title: string }) => string);
    // The name without extension that should be used to
    // create the `.d.ts` and `.js` files.
    // Default: outDir === entry ? "index" : title
    outName?:
        | string
        | ((ctx: { entry: string; outDir: string; title: string }) => string);
}

Tree-shaking

If you would like to use the benefits of eg. TypeScript namespace barrels without losing tree-shaking, you can give tree-shake-import-namespaces a try!

Credits

• bencoveney/barrelsby