Skip to main content

Pre-Release Notice: TypeScript module export changes

· 3 min read

We're changing the way we export modules in our TypeScript SDK to align with modern Typescript best practices and improve compatibility across different environments.

What's New?​

Starting November 1st 2025, you'll see 2 changes in the Typescript SDKs:

  • New exports field: You'll notice a new exports field in the SDK's package.json file:

    {
      "exports": {
        ".": {
          "import": {
            "types": "./dist/esm/types/index.d.ts",
            "default": "./dist/esm/index.js"
          },
          "require": {
            "types": "./dist/cjs/types/index.d.ts",
            "default": "./dist/cjs/index.js"
          }
        },
        "./metadata": {
          "import": {
            "types": "./dist/esm/types/metadata/index.d.ts",
            "default": "./dist/esm/metadata/index.js"
          },
          "require": {
            "types": "./dist/cjs/types/metadata/index.d.ts",
            "default": "./dist/cjs/metadata/index.js"
          }
        }
      }
    }

  • Updated internal imports: You'll also notice that the internal SDK imports use the .js extension, following TypeScript's recommended best practices.

Why are these updates needed ?​

These change enable SDK users to:

  • Reduce bundle size: Avoid unwanted imports that can impact JavaScript file bundling for browser applications
  • Improve import clarity: Use more explicit import patterns that align with our documented best practices
  • Catch errors earlier: Import-related runtime failures will now be caught at compile time for ESM users
  • Enhance compatibility: The same code can run seamlessly on both browsers and Node.js environments

Testing SDKs​

To test your Typescript SDK with these changes before the November 1st release date, reach out to your APIMatic point of contact or contact our team at support@apimatic.io

Potential Breaking Changes​

Following these changes, there are a few rare edge cases where changes can be breaking. These cases occur for users who use the SDK in ways that are unconventional or bad practice:

info

If SDK users followed Typescript best practices and the import patterns shown in our SDK Documentation while building their integrations, no changes are required.

SDK users that use any of the following edge cases may need to update their SDK integrations:

  1. Node.js ESM Users with Default Imports

    Affected code pattern:

    // example.ts
    import sdk from @company/some-sdk;
    const client = new sdk.Client();

    Recommended change: Default imports can be error-prone and difficult to reason about since different runtimes and bundlers often interpret them differently in subtle ways. The following is a standards compliant way of fixing it:

    // Option 1: Namespace import
    import * as sdk from @company/some-sdk;
    const client = new sdk.Client();

    // Option 2: Named import (preferred)
    import { Client } from @company/some-sdk;
    const client = new Client();

  2. CommonJS Users with Deep Imports

    Affected code patterns:

    // example.js
    const { Client } = require("@company/some-sdk/dist/cjs/index");
    // or
    const { Client } = require("../node_modules/@company/some-sdk/dist/cjs/index");

    Recommended fix:

    // example.js
    const { Client } = require("@company/some-sdk");

Action Required​

For API providers using APIMatic generated TypeScript SDKs:

  • Review internal integrations: Audit any internal applications, services, or tools that use your TypeScript SDK to ensure they follow the recommended patterns shown above.

  • Notify your SDK consumers: Share the import pattern examples from this changelog with your SDK users, emphasizing that integrations following TypeScript best practices won't require any changes.

    Timeline: Complete these actions before November 1st, 2025 when the changes take effect.