barrels

Appearance

namespace ​

ts
interface NamespaceBarrelConfig {
    type: "namespace";
    name?: string | ((filePath: string) => string);
    types?: "merge" | "nested" | "flat";
    indentation?: number;
    banner?: boolean | string;
    directories?: string | string[];
    files: string | string[];
    include?: string | RegExp | readonly (string | RegExp)[];
    exclude?: string | RegExp | readonly (string | RegExp)[];
    output?: string | ((directory: string) => string);
    extensions?: "auto" | false | Record<string, string>;
    resolveExports?: boolean;
    transformSources?: (sources: Source[]) => Source[] | Promise<Source[]>;
    transformBarrel?: (barrel: string) => string | Promise<string>;
}

This config creates TypeScript namespace barrel files, with varying options for how to handle encountered type definitions.

Example ​

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

export default defineConfig([
    {
        type: "namespace",
        name: "Barrel",
        files: "./src/utils/*.ts",
        output: "./src/utils/index.ts",
        removeExtensions: true,
    },
]);
ts
// Generated by @monstermann/barrels
/* eslint-disable */
/* prettier-ignore */
// dprint-ignore-file
// biome-ignore lint: disable

import { foo as _foo } from "./foo"
import { bar as _bar } from "./bar";
import { baz as _baz } from "./baz";

export namespace Barrel {
    export const foo = _foo;
    export const bar = _bar;
    export const baz = _baz;
}

Options ​

name ​

ts
interface NamespaceBarrelConfig {
    name?: string | ((filePath: string) => string);
}

Defines the name of the namespace. If omitted, the output file name will be used, or the output directory name if the file name was index.

type ​

ts
interface NamespaceBarrelConfig {
    types?: "merge" | "nested" | "flat";
}

This defines how type definitions should be handled, flat by default.

nested ​

Using this option will result with all type exports being included in the namespace.

ts
import type { Foo as _Foo } from "./foo";
import type { Bar as _Bar } from "./bar";
import type { Baz as _Baz } from "./baz";

export namespace Foo {
    export type Foo = _Foo;
    export type Bar = _Bar;
    export type Baz = _Baz;
}

flat ​

Using this option will result with all type exports being re-exported as-is, including only values in the namespace.

ts
export type { Foo } from "./foo";
export type { Bar } from "./bar";
export type { Baz } from "./baz";

export namespace Foo {}

While this might look like a conflict, TypeScript is smart in figuring out whether Foo is the type definition or the namespace, depending on your usage.

merge ​

A mixture between nested and flat - Using this option will result with type exports that have the same name as the namespace being re-exported as-is, and all others are included in the namespace.

ts
export type { Foo } from "./foo";
import type { Bar as _Bar } from "./bar";
import type { Baz as _Baz } from "./baz";

export namespace Foo {
    export type Bar = _Bar;
    export type Baz = _Baz;
}

While this might look like a conflict, TypeScript is smart in figuring out whether Foo is the type definition or the namespace, depending on your usage.

indentation ​

ts
interface NamespaceBarrelConfig {
    indentation?: number;
}

Controls how many spaces to use for indenting, by default 4.

ts
interface Config {
    banner?: boolean | string;
}

When enabled (as is by default), prepends a banner:

ts
// Generated by @monstermann/barrels
/* eslint-disable */
/* prettier-ignore */
// dprint-ignore-file
// biome-ignore lint: disable

You can turn this off by setting it to false:

ts
export default defineConfig([
    {
        banner: false,
    },
]);

Or define your own:

ts
export default defineConfig([
    {
        banner: "// My custom banner",
    },
]);

directories ​

ts
interface Config {
    directories?: string | string[];
}

Paths or globs to directories to create the barrel files in, by default set to process.cwd().

ts
export default defineConfig([
    {
        // For each directory in "./src/utils/":
        directories: "./src/utils/*",
        // Find all immediate ".ts" files:
        files: "*.ts",
        // And create an "index.ts" in the respective directory:
        output: "index.ts",
    },
]);

files ​

ts
interface Config {
    files: string | string[];
}

Paths or globs to include files from, relative to each directory.

include ​

ts
interface Config {
    include?: string | RegExp | readonly (string | RegExp)[];
}

RegExps or globs to quickly filter files. The checks are made against resolved absolute paths.

exclude ​

ts
interface Config {
    exclude?: string | RegExp | readonly (string | RegExp)[];
}

RegExps or globs to quickly exclude files. The checks are made against resolved absolute paths, for example to kick out all external dependencies:

ts
export * from "external-dependency";
export const foo = true;
ts
export default defineConfig([
    {
        type: "flat",
        files: "./source.ts",
        output: "./index.ts",
        // Extract all exports from "source.ts":
        resolveExports: true,
        // Kick out re-exported modules coming from node_modules:
        exclude: "**/node_modules/**",
    },
]);
ts
export { foo } from "./source.ts";

output ​

ts
interface Config {
    output?: string | ((directory: string) => string);
}

The path to the file the barrel contents should be written to, relative to each directory, index.ts by default.

extensions ​

ts
interface Config {
    extensions?: "auto" | false | Record<string, string>;
}

Controls how file extensions are handled when building import/export declarations, by default "auto".

ts
export default defineConfig([
    {
        // Remove all extensions:
        extensions: false,
        // Remap specific extensions:
        extensions: {
            ts: "js",
        },
        // Decide based on `tsconfig` settings:
        // If `allowImportingTsExtensions` is turned on, leaves extensions as-is.
        // If `moduleResolution` is set to `bundler`, removes all extensions.
        // Otherwise eg. `ts` gets remapped to `js`.
        extensions: "auto",
    },
]);

removeExtensions ​

ts
interface Config {
    removeExtensions?: boolean;
}

This allows you to remove all extensions, useful when tsconfig.compilerOptions.moduleResolution is set to bundler.

resolveExports ​

ts
interface Config {
    resolveExports?: boolean;
}

Enabled by default when using { type: "namespace" } or { type: "record" }.

When enabled, will recursively extract individual export declarations from encountered files. This is necessary for some barrel types, but you can also use this to control what exactly is being exported instead of re-exporting all encountered files as export * from "file.ts".

source.ts
ts
export const foo = true;

Before:

ts
export default defineConfig([
    {
        type: "flat",
        files: "./source.ts",
        output: "./index.ts",
    },
]);
ts
export * from "./source.ts";

After:

ts
export default defineConfig([
    {
        type: "flat",
        files: "./source.ts",
        output: "./index.ts",
        resolveExports: true,
    },
]);
ts
export { foo } from "./source.ts";

transformSources ​

ts
interface Config {
    transformSources?: (sources: Source[]) => Source[] | Promise<Source[]>;
}

This allows you to modify the encountered files or exports before constructing barrel files.

See API/Guide for an overview!

transformBarrel ​

ts
interface Config {
    transformBarrel?: (barrel: string) => string | Promise<string>;
}

This allows you to modify the created barrel contents before writing to disk.