Disabling barrel files

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

Configuring barrel file generation

The useIndexModules configuration option controls barrel file generation. Configure this option by adding or modifying useIndexModules under the typescript section in the gen.yaml file:

By default, useIndexModules is set to true so that Speakeasy generates barrel files that look like this:

SDK consumers can then import modules from barrel files as follows:

If you set useIndexModules to false, Speakeasy will not generate these barrel files. Consumers need to import modules directly from the individual module files:

Pros and cons of using barrel files

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

On the other hand, disabling barrel files has some advantages:

• Superior tree shaking performance: Barrel files can significantly impair effective tree shaking in modern bundlers. When importing modules from a barrel file, bundlers often struggle to determine which exports are actually used, leading to the inclusion of unused code. Disabling barrel files allows bundlers to accurately track dependencies and exclude unused code, resulting in smaller production bundles.

• Enhanced developer tooling: Without barrel files, IDE “Go to Definition” features (for example, Cmd/Ctrl + Click) link directly to the source file containing the implementation, rather than 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 build tools have to process. When you remove 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

Making the right choice

Whether you should 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

Additional reading

Visit the following pages to learn more about generating SDKs with Speakeasy:

• TypeScript configuration options
• Lean SDKs with standalone functions