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:

# .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:

// petstore sdk

// src/models/errors/index.ts

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:

// 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:

// 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:

  • Improved Tree Shaking: Barrel files can be detrimental to effective tree shaking. If not using a bundler with tree shaking enables, all files imported in the barrel will be bundled, even if unused. This results in increased bundle size and slower load times.
  • Better Editor/IDE Experience: When a user jumps to the definition (e.g., CMD + Click or similar) of an SDK method or object, users will be brought to the actual definition instead of the barrel file.
  • Increased Build Times: Barrel files can slow project tooling by causing a chain of dependent imports across modules. This can impair tree shaking, leading to larger bundles and slower load times.

Ultimately, the decision to use useIndexModules depends on project priorities:

  • Prioritizing bundle size and performance? Disable barrel files.
  • Prioritize developer convenience? Keep barrel files enabled.
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