Product Updates

Custom code regions: SDK customization without limits

Emre Tezisci

January 15, 2025

We’re excited to announce Custom Code Regions, a powerful new feature that puts you in complete control of your SDKs. Whether you need to add custom methods, integrate third-party libraries, or build bespoke functionality, Custom Code Regions let you do it all—directly in the generated SDK. And the best part? Your customizations persist across updates, with no need to edit your OpenAPI spec or deal with workarounds.

What are Custom Code Regions?

Custom Code Regions give developers the ability to embed their own code into specific parts of the generated SDK. Using foldable region syntax, you can define areas in the codebase for your custom logic. These regions are preserved during regenerations, meaning you can enhance the SDK while maintaining its stability.

Whether you’re adding helper methods, extending SDK functionality, or introducing custom integrations, Custom Code Regions make it easy to personalize your SDK without impacting the underlying OpenAPI spec.

How It Works

Custom Code Regions leverage foldable region syntax, inspired by Visual Studio Code, to define and preserve custom code sections. Here’s an example:

import { ClientSDK } from "./lib/sdks.js";
// #region imports
import chalk from 'chalk';
// #endregion imports

class Acme extends ClientSDK {
  // ... generated code ...

  // #region sdk-class-body
  greet(name: string): string {
    return chalk.green(`Hello, ${name}!`);
  }
  // #endregion sdk-class-body
}

During SDK generation, the generator identifies these regions and ensures your custom code is seamlessly integrated into the updated SDK. This process ensures consistent formatting while preserving customizations.

Why Custom Code Regions?

For developers, flexibility is key. Before Custom Code Regions, SDK customization options were limited to overlays and hooks, which are powerful tools but sometimes require modifying the OpenAPI spec or working programmatically within the generation process. Custom Code Regions provide a simpler, more direct approach:

Direct Control: Write custom logic right in the SDK, bypassing spec modifications or hook configurations.
Persistent Changes: Customizations are preserved during SDK regenerations, so you don’t have to worry about losing your code when the spec changes.
Unlimited Flexibility: From helper methods to advanced integrations, you can do anything with Custom Code Regions.

How Custom Code Regions Fit with Overlays and Hooks

Custom Code Regions complement overlays and hooks, giving developers three levels of control over their SDKs:

Customization Tool	Purpose	Key Use Case
Overlays	Modify the OpenAPI spec for structural or schema-related changes.	Adding paths, tweaking parameters, or updating models.
Hooks	Intercept and modify SDK generation programmatically during the build.	Dynamic updates, injecting logic at specific stages.
Custom Code Regions	Insert custom logic directly into the generated SDK code at runtime.	Adding helper methods, third-party integrations, or SDK-specific tweaks.

By combining these tools, you can build SDKs that are perfectly tailored to your needs.

Ready to Try Custom Code Regions?

Custom Code Regions are now available for enterprise customers in TypeScript and Python SDKs generated with the latest Speakeasy CLI. Support for additional languages is on the way, so stay tuned.

📚 Dive into the documentation:
🔗 Custom Code Regions Documentation