Speakeasy Logo
Skip to Content
DocumentationCustomizeTypeScriptConfiguring module format

Configuring Module Format

Modern SDKs need to balance compatibility with performance. The moduleFormat option in the SDK generator allows developers to control whether an SDK is built for CommonJS (CJS), ECMAScript Modules (ESM), or both. This choice impacts bundle size, tree-shaking performance, and compatibility with Node.js and modern bundlers.

How to Configure Module Format

To configure the module format, update gen.yaml (which is often located in the SDK’s .speakeasy directory) file under the typescript section:

Supported Options

  • "commonjs" (default): Builds SDK for CommonJS. Widely supported across Node.js environments but less optimized for modern bundlers and tree-shaking.
  • "esm": Builds SDK for ECMAScript Modules, the modern standard for JavaScript modules. Provides optimal tree-shaking and significantly smaller bundles when used with bundlers like Webpack, Rollup, or Vite.
  • "dual": Builds SDK for both CJS and ESM formats. Provides the best of both worlds - ESM’s superior tree-shaking and bundle optimization while maintaining compatibility with older CommonJS environments. The slight build time increase is often worth the flexibility and performance benefits.

Module Format Overview

moduleFormat determines the module system targeted during SDK build. It impacts:

  • Node.js project compatibility,
  • Bundler tree-shaking capabilities,
  • SDK bundle size, and
  • Build performance.

Example Outputs for Each Option

CommonJS (Default)

When configured with commonjs:

ESM

When configured with esm:

Dual

When configured with dual:

How to Decide Which Format to Use

Use CommonJS (commonjs) if…

  • The SDK is used primarily in Node.js environments or older projects.
  • Bundle size optimization is not a critical requirement.
  • Maximum compatibility with legacy systems is required.

Use ESM (esm) if…

  • SDK consumers use modern bundlers like Vite, Webpack, or Rollup.
  • Tree-shaking and bundle size optimization are top priorities.
  • The project already uses ESM throughout.
  • Leveraging the latest JavaScript features and tooling is important.

Use Dual Mode (dual) if…

  • Support for both modern and legacy environments is required.
  • ESM’s superior tree-shaking while maintaining CommonJS compatibility is desired.
  • The SDK will be used in diverse environments with different module requirements.
  • Developer experience and maximum flexibility are priorities.

Recommendation

For most modern projects, the dual format is recommended. This ensures the SDK works seamlessly in any environment while still providing the performance benefits of ESM when used with modern bundlers.

Additional Reading

Last updated on