configure-sdk-options

Files (8)

• SKILL.md
• csharp.md · content/languages/
• go.md · content/languages/
• java.md · content/languages/
• php.md · content/languages/
• python.md · content/languages/
• ruby.md · content/languages/
• typescript.md · content/languages/

SKILL.md (first lines)

# 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:

| Language | Guide | Key Features |
|----------|-------|--------------|
| TypeScript | [content/languages/typescript.md](content/languages/typescript.md) | Zod validation, React Query, standalone functions, dual module format |
| Python | [content/languages/python.md](content/languages/python.md) | Pydantic models, async modes (both/split), uv/poetry support |
| Go | [content/languages/go.md](content/languages/go.md) | Response formats, interface generation, K8s integration |
| Java | [content/languages/java.md](content/languages/java.md) | Builder pattern, Gradle customization, Maven Central publishing |
| C# | [content/languages/csharp.md](content/languages/csharp.md) | Async/await, cancellation tokens, DI integration, NuGet |
| PHP | [content/languages/php.md](content/languages/php.md) | Laravel integration, Guzzle config, Packagist publishing |
| Ruby | [content/languages/ruby.md](content/languages/ruby.md) | Sorbet typing, Rails integration, RubyGems publishing |

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

| Input | Required | Description |
|-------|----------|-------------|
| Existing SDK | Yes | SDK with `.speakeasy/workflow.yaml` already created |
| Target language | Yes | TypeScript, Python, Go, Java, C#, PHP, or Ruby |

## Outputs

| Output | Description |
|--------|-------------|
| Updated gen.yaml | Language-specific configuration |
| Hook files | Custom hooks if enabled |

## Prerequisites

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

```bash
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:

```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

```yaml
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
```

| Feature | Notes |
|---------|-------|
| Zod validation | Automatic for all models |
| Tree-shaking | Use `moduleFormat: dual` + standalone functions |
| JSR publishing | Create `jsr.json`, run `deno publish` |
| npm publishing | Standard `npm publish` |

**Standalone functions for tree-shaking:**
```typescript
import { TodoCore } from "my-sdk/core.js";
import { todosCreate } from "my-sdk/funcs/todosCreate.js";
const sdk = new TodoCore({ apiKey: "..." });
```

## Python Configuration

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

| Feature | Notes |
|---------|-------|
| Pydantic models | Automatic for all models |
| Async mode `both` | `sdk.method()` and `sdk.method_async()` |
| Async mode `split` | `SDK()` and `AsyncSDK()` constructors |
| PyPI publishing | `uv publish` or `poetry publish` |

**Async patterns:**
```python
# asyncMode: both (default)
result = sdk.users.list()           # sync

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills