Configure Sdk Options

Configure SDK Options

Configure gen.yaml options for an existing Speakeasy SDK. Supports TypeScript, Python, Go, Java, C#, PHP, and Ruby.

For new SDK projects: Use start-new-sdk-project skill instead. This skill is for configuring an existing SDK.

Language-Specific Guides

For comprehensive configuration details, see the language-specific guides:

These guides include detailed configuration options, code examples, framework integrations, and publishing instructions.

When to Use

• Configuring language-specific gen.yaml options on an existing SDK
• Setting up SDK hooks, async patterns, or publishing
• Configuring runtime behavior (retries, timeouts, server selection) in application code
• User says: "configure SDK", "gen.yaml options", "SDK config", "runtime override", "per-call config"
• User asks about: Zod, Pydantic, NuGet, PyPI, npm, Maven Central, Packagist, RubyGems

Inputs

Outputs

Prerequisites

You must have an existing SDK with .speakeasy/workflow.yaml. If not, run:

speakeasy quickstart --skip-interactive --output console \
  -s openapi.yaml -t <language> -n "MySDK" -p "<package-name>"

Common Configuration (All Languages)

These options apply to all SDK targets in gen.yaml:

<language>:
  version: 1.0.0
  packageName: "my-sdk"

  # Method signatures
  maxMethodParams: 4              # Params before request object
  flatteningOrder: parameters-first

  # Error handling
  responseFormat: flat            # or "envelope" (Go)
  clientServerStatusCodesAsErrors: true

TypeScript Configuration

typescript:
  version: 1.0.0
  packageName: "@myorg/my-sdk"
  moduleFormat: dual              # esm, commonjs, or dual
  zodVersion: v4-mini             # v3, v4, or v4-mini
  enableCustomCodeRegions: true   # For custom code
  enableReactQuery: true          # React Query hooks

Standalone functions for tree-shaking:

import { TodoCore } from "my-sdk/core.js";
import { todosCreate } from "my-sdk/funcs/todosCreate.js";
const sdk = new TodoCore({ apiKey: "..." });

Python Configuration

python:
  version: 1.0.0
  packageName: "my-sdk"
  asyncMode: both                 # both or split
  packageManager: uv              # uv or poetry
  envVarPrefix: ""                # Prefix for env config

Async patterns:

# asyncMode: both (default)
result = sdk.users.list()           # sync
result = await sdk.users.list_async() # async

# asyncMode: split
sdk = MySDK()                       # sync only
async_sdk = AsyncMySDK()            # async only

Go Configuration

go:
  version: 0.1.0
  packageName: github.com/myorg/my-sdk
  maxMethodParams: 2
  methodArguments: require-security-and-request
  responseFormat: envelope
  flattenGlobalSecurity: true

Interface generation for testing:

go install github.com/vburenin/ifacemaker@latest
go install github.com/vektra/mockery/v2@latest
ifacemaker --file consumers.go --struct Consumers --iface ConsumersSDK --output consumers_i.go
mockery

Java Configuration

java:
  version: 1.0.0
  groupID: com.myorg
  artifactID: my-sdk
  packageName: com.myorg.mysdk
  methodArguments: require-security-and-request

Client usage:

MySdk sdk = MySdk.builder()
    .security(Security.builder().apiKey("key").build())
    .build();

C# Configuration

csharp:
  version: 1.0.0
  packageName: MyOrg.MySDK
  dotnetVersion: "6.0"
  baseErrorName: MySDKException

Async with cancellation:

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await sdk.Users.ListAsync(cancellationToken: cts.Token);

PHP Configuration

php:
  version: 1.0.0
  packageName: myorg/my-sdk
  namespace: MyOrg\MySDK

Security callback for token refresh:

$sdk = MySDK\MySDK::builder()
    ->setSecuritySource(fn() => getTokenFromCache() ?? refreshToken())
    ->build();

Ruby Configuration

ruby:
  version: 1.0.0
  packageName: my-sdk
  module: MySdk
  typingStrategy: sorbet          # sorbet or none

SDK Hooks (All Languages)

Enable custom hooks with enableCustomCodeRegions: true. Hook files are preserved across regeneration.

See customize-sdk-hooks skill for detailed hook implementation.

Runtime Overrides

Runtime behavior can be configured at SDK instantiation or per-call. These override gen.yaml defaults.

Server Selection

Define server IDs in OpenAPI spec, then select at runtime:

# OpenAPI spec
servers:
  - url: https://api.example.com
    x-speakeasy-server-id: production
  - url: https://sandbox.example.com
    x-speakeasy-server-id: sandbox

Retry Overrides

Override retry behavior per-call (spec defaults set via x-speakeasy-retries):

TypeScript:

const res = await sdk.payments.create({ amount: 1000 }, {
  retries: {
    strategy: "backoff",
    backoff: { initialInterval: 1000, maxInterval: 30000, maxElapsedTime: 120000, exponent: 2.0 },
    retryConnectionErrors: true,
  },
});

Python:

from sdk.utils import BackoffStrategy, RetryConfig
res = sdk.payments.create(amount=1000, retries=RetryConfig("backoff",
    backoff=BackoffStrategy(1000, 30000, 120000, 2.0), retry_connection_errors=True))

Go:

res, err := sdk.Payments.Create(ctx, req, operations.WithRetries(retry.Config{
    Strategy: "backoff", Backoff: &retry.BackoffStrategy{
        InitialInterval: 1000, MaxInterval: 30000, MaxElapsedTime: 120000, Exponent: 2.0},
    RetryConnectionErrors: true}))

Timeout Overrides

Set global timeout on SDK constructor, or per-call:

Pagination Usage

SDK auto-generates pagination helpers when x-speakeasy-pagination is set in spec:

// Auto-iterate all pages
for await (const user of await sdk.users.list({ limit: 50 })) {
  console.log(user.name);
}

// Manual pagination
let page = await sdk.users.list({ limit: 50 });
while (page) {
  for (const user of page.data) { console.log(user.name); }
  page = await page.next();
}

Decision Framework

What NOT to Do

• Do NOT use this skill for initial SDK generation - use start-new-sdk-project
• Do NOT edit generated files outside custom code regions
• Do NOT modify files in src/ that aren't in preserved directories (hooks, extra)

Troubleshooting

After Making Changes

After modifying gen.yaml configuration, prompt the user to regenerate the SDK:

Configuration complete. Would you like to regenerate the SDK now with speakeasy run?

If the user confirms, run:

speakeasy run --output console

Changes to gen.yaml only take effect after regeneration.

Related Skills

• start-new-sdk-project - Initial SDK generation
• customize-sdk-hooks - Detailed hook implementation
• manage-openapi-overlays - Spec customization