Disabling Barrel Files

By default, the SDK generator creates “barrel files” or “index.ts” files that centralize module re-exports within an SDK package.

Configuring Barrel File Generation

The useIndexModules configuration option controls barrel file generation, which centralizes module re-exports. Configure this option by adding or modifying useIndexModules in gen.yaml file under the typescript section:

<sdk-root>/.speakeasy/gen.yaml
typescript:

  # add or modify `useIndexModules`

  useIndexModules: true # or false

  # other Typescript configuration options...

With useIndexModules set to true (the default), Speakeasy will generate barrel files that look like this:

<sdk-root>/src/models/errors/index.ts
// petstore sdk

export * from "./apierror.js";

export * from "./apierrorinvalidinput.js";

export * from "./apierrornotfound.js";

export * from "./apierrorunauthorized.js";

export * from "./httpclienterrors.js";

export * from "./sdkvalidationerror.js";

Consumers of the SDK could then import from the barrel file:

example.ts
// somewhere in a consumer's code code

import {

  ApiErrorInvalidInput,

  ApiErrorNotFound,

  ApiErrorUnauthorized,

  SDKValidationError,

} from "petstore/models/errors";

Conversely, with useIndexModules set to false, Speakeasy will not generate these barrel files. Consumers would need to import directly from the individual module files:

example.ts
// somewhere in a consumer's code

import { ApiErrorInvalidInput } from "petstore/models/errors/apierrorinvalidinput.js";

import { ApiErrorNotFound } from "petstore/models/errors/apierrornotfound.js";

import { ApiErrorUnauthorized } from "petstore/models/errors/apierrorunauthorized.js";

import { SDKValidationError } from "petstore/models/errors/sdkvalidationerror.js";

Pros and Cons of Using Barrel Files

Barrel files, or index.ts files, provide a convenient way to centralize imports for SDK consumers. When useIndexModules is true, users can import from a single entry point rather than having to supply the exact file structure of the package’s resources.

On the other hand, disabling barrel files can have some advantages:

  • Superior Tree Shaking Performance: Barrel files can significantly impair effective tree shaking in modern bundlers. When importing from a barrel file, bundlers often struggle to determine which exports are actually used, leading to the inclusion of unused code. By disabling barrel files, you ensure that bundlers can accurately track dependencies and exclude unused code, resulting in smaller production bundles.

  • Enhanced Developer Tooling: Without barrel files, your IDE’s “Go to Definition” feature (e.g., CMD/Ctrl + Click) takes you directly to the source file containing the implementation, rather than navigating through an intermediate barrel file. This improves code navigation and makes it easier to understand the codebase structure.

  • Faster Build Performance: Barrel files create additional import chains that your build tools must process. By removing these intermediary files:

    • Build tools process fewer files during compilation
    • Module dependency graphs become simpler and more efficient
    • Hot module replacement (HMR) becomes more precise
    • TypeScript type checking performance improves
Info Icon

Performance tip

When combined with moduleFormat: dual, disabling barrel files provides optimal tree-shaking performance. The ESM format’s static analysis capabilities work best with direct imports, allowing bundlers to eliminate unused code more effectively.

Making the Right Choice

The decision to use useIndexModules depends on your project’s priorities:

  • Disable barrel files (useIndexModules: false) when:
    • Bundle size optimization is critical
    • You’re using modern bundlers like Webpack, Rollup, or Vite
    • Build performance is important
    • Your team values clear dependency paths
  • Keep barrel files (useIndexModules: true) when:
    • Import convenience is more important than bundle optimization
    • Your project doesn’t use a bundler with tree-shaking
    • You prefer centralized import management
Info Icon

Recommendation

For modern web applications, we recommend setting useIndexModules: false. While barrel files offer convenient imports, the performance benefits of direct imports typically outweigh this convenience, especially when using modern IDEs with good import management features.

Info Icon

Note

Note: This article draws information from the following sources: - Why you should avoid barrel files in Javascript (opens in a new tab) by Bartosz Łaniewski - Please Stop Using Barrel Files (opens in a new tab) by Dominik Dorfmeister

Additional Reading