@valfuse-node/barrel

Generate a deterministic TypeScript barrel (index.ts) from an explicit directory of source modules. The generator creates named export * statements for selected .ts and .tsx files; it does not inspect module contents or decide which symbols should be public.

npm install --save-dev @valfuse-node/barrel

Requires Node.js 22 or newer to run the CLI or programmatic generator. The package declares engines.node >=22. Generated barrel files are ordinary TypeScript source and do not need this package at runtime.

Contents

• Quick start
• Configuration
• Files included by the scan
• Generate and check
• Public API and dependency guidance
• Node.js API
• Troubleshooting
• Release history
• Support
• License

Quick start

Given source modules such as:

src/rules/
├── email.ts
├── required.ts
└── internal.test.ts

Add a barrel section to the shared valfuse.yaml in the project root:

barrel:
  input_dir: src/rules
  output_file: src/rules/index.ts
  include:
    - email.ts
    - required.ts

Run the generator:

npx valfuse-barrel

It writes a sorted barrel that you can import from the directory:

// src/rules/index.ts
/**
 * Generated by @valfuse-node/barrel. Do not edit manually.
 */
export * from "./email";
export * from "./required";

import { emailRule, requiredRule } from "./rules";

The generator is framework-neutral. Express projects can use it to expose route, middleware, or schema modules through a stable TypeScript entry point; it does not add Express-specific runtime code.

Configuration

The CLI reads the barrel section of valfuse.yaml from the current working directory. The same file can also contain assets and localization sections. Relative paths are resolved from that directory; absolute file paths are also accepted. Pass a different config with --config <file>.

barrel:
  input_dir: src
  output_file: src/index.ts

  # Optional exact filenames to expose. Omit it or use [] to scan all eligible
  # direct children.
  include: []

  # Optional exact filenames to omit during automatic scanning.
  exclude:
    - internal.ts

| Option | Default | Purpose | | ------------- | -------------- | -------------------------------------------------------- | | input_dir | src | Directory to scan; the scan is not recursive | | output_file | src/index.ts | Generated file; must have a .ts extension | | include | [] | Exact filename allowlist; empty means automatic scanning | | exclude | [] | Exact filename denylist for automatic scanning |

The YAML config uses snake_case names. The programmatic API uses camelCase names. Unknown YAML keys, empty paths, invalid lists, duplicate filenames, or filenames present in both include and exclude are errors. Include/exclude entries must be file names without directory paths.

Files included by the scan

Only direct-child regular files with .ts or .tsx extensions are eligible. The generator skips:

• hidden files;
• index.ts and index.tsx;
• TypeScript declaration files (.d.ts);
• *.test.ts, *.test.tsx, *.spec.ts, *.spec.tsx, *.stories.ts, and *.stories.tsx.

Use include to define a stable public surface when the folder contains internal modules. An allowlisted file must exist directly under input_dir and must pass the same eligibility checks. exclude is useful for automatic scans; when include is non-empty, it already defines the selected files.

Generate and check

npx valfuse-barrel
npx valfuse-barrel --check
npx valfuse-barrel --config config/valfuse.yaml
npx valfuse-barrel --help

| Option | Behavior | | ----------------- | ----------------------------------------- | | --config <file> | Read another YAML config file | | --check | Fail if generated output is missing/stale | | --help, -h | Print CLI usage and defaults |

--check does not write files. It exits with an error if output is missing or does not match the current source selection. Existing output is rewritten only when the generated content changes. Output order is deterministic.

Add repeatable commands to package.json:

{
  "scripts": {
    "barrel:generate": "valfuse-barrel",
    "barrel:check": "valfuse-barrel --check"
  }
}

Generate after changing the selected source modules. Run npm run barrel:check in CI, and commit generated files when they form part of the package's public source API.

The scripts above are for consumer projects where the package binary is on the local npm script path. In this monorepo, the React, Vue, and Express examples call the built workspace CLI directly with Node.js (node ../../packages/barrel/dist/cli/index.js) so generator execution is consistent in local runs and Turbo CI. See each example README for its workspace commands.

Public API and dependency guidance

This generator creates only export * from "..." statements. It does not re-export default exports, resolve duplicate names, create aliases, or infer which exports are intended to be public. Use an include allowlist or hand write explicit exports when you need those controls.

Generation is non-recursive by design. For multiple directories, add a separate config file with a barrel section for each directory and run each explicitly:

npx valfuse-barrel --config valfuse.rules.yaml
npx valfuse-barrel --config valfuse.components.yaml

Internal modules should import one another directly instead of importing from the generated barrel they are exported through. This avoids circular module edges. A root barrel only includes a feature barrel when that file is a direct child of the root config's input_dir.

The command-line tool belongs in development dependencies. Its generator API can also be imported from the standalone package or from the explicit Node.js-only @valfuse-node/core/barrel subpath; it is not part of the core root import.

Node.js API

import { generateBarrel } from "@valfuse-node/barrel";

const result = await generateBarrel({
  cwd: process.cwd(),
  config: {
    inputDir: "src/rules",
    outputFile: "src/rules/index.ts",
    include: ["email.ts", "required.ts"],
  },
});

console.log(result.moduleCount, result.changed);

GenerateBarrelOptions accepts optional cwd, partial camelCase config, and check. Omitted config fields use these defaults:

{
  inputDir: "src",
  outputFile: "src/index.ts",
  include: [],
  exclude: [],
}

The package entry exports generateBarrel and DEFAULT_BARREL_GENERATOR_CONFIG. Its public types are BarrelGeneratorConfig, BarrelGeneratorConfigInput, GenerateBarrelOptions, and GenerateBarrelResult.

On success, generateBarrel returns GenerateBarrelResult with moduleCount (the number of re-exported files), outputFile (an absolute path), and changed (whether the generator wrote a new version). It throws an Error if the input directory is missing, the config is invalid, no modules are selected, an allowlisted module is missing, or check mode finds stale output.

Troubleshooting

• No TypeScript modules found: check input_dir, file extensions, and the default exclusions. The generator never descends into child directories.
• Included module not found: use the exact eligible file name, including .ts or .tsx, relative to input_dir.
• Duplicate exports or a circular import: narrow include or hand-write explicit exports; keep imports between modules pointed at the modules themselves.
• CI reports stale output: run npm run barrel:generate and commit the resulting file.

See the repository README for package selection and the architecture guide for dependency boundaries.

Release history

See the monorepo changelog.

Support

For usage questions, bug reports, and feature requests, see the project support guide. For security reports, follow the security policy. Do not use public issues for security reports.

License

MIT