# Typescript Configuration Options

This section details the available configuration options for the TypeScript SDK. All configuration is managed in the `gen.yaml` file under the `typescript` section.

## Version and general configuration

```yml
typescript:
  version: 1.2.3
  author: "Author Name"
  packageName: "custom-sdk"
```

## Additional JSON package

```yml
typescript:
  additionalPackageJSON:
    license: "MIT"
```

## Additional dependencies

```yml
typescript:
  additionalDependencies:
    dependencies:
      axios: "^0.21.0"
    devDependencies:
      typescript: "^4.0.0"
    peerDependencies:
      react: "^16.0.0"
```

## Package scripts and examples

```yml
typescript:
  additionalScripts:
    format: "prettier --write src"
    docs: "typedoc --out docs src"
    custom-test: "vitest run --coverage"
  generateExamples: true
  compileCommand: ["npm", "run", "build"]
  usageSDKInit: "new Petstore({})"
  usageSDKInitImports:
    - package: "@petstore/sdk"
      import: "Petstore"
      type: "packageImport"
```

### How scripts are merged

The feature uses an override strategy where additional scripts take precedence over default scripts:

1. **Default scripts** are generated automatically based on SDK configuration:

```json
{
  "lint": "eslint --cache --max-warnings=0 src",
  "build": "tsc",
  "prepublishOnly": "npm run build"
}
```

2. **Test scripts** are added if tests are enabled:

```json
{
  "test": "vitest run src --reporter=junit --outputFile=.speakeasy/reports/tests.xml --reporter=default",
  "check": "npm run test && npm run lint"
}
```

3. **Additional scripts** override defaults if they have the same name:

```yml
typescript:
  additionalScripts:
    build: "custom-build-command"  # Replaces default "tsc" build
    deploy: "npm publish"           # Adds new script
```

4. **Result** in `package.json`:

```json
{
  "scripts": {
    "build": "custom-build-command",  // Overridden
    "check": "npm run test && npm run lint",
    "deploy": "npm publish",           // Added
    "lint": "eslint --cache --max-warnings=0 src",
    "prepublishOnly": "npm run build",
    "test": "vitest run src --reporter=junit --outputFile=.speakeasy/reports/tests.xml --reporter=default"
  }
}
```

## Method and parameter management

```yml
typescript:
  maxMethodParams: 3
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"
```

## Security configuration

```yml
typescript:
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
```

## Module management

```yml
typescript:
  moduleFormat: "dual"
  useIndexModules: true
  legacyFileNaming: false
```

<Callout title="Performance optimization" type="info">
For optimal bundle size and tree-shaking performance in modern applications, consider using `moduleFormat: "esm"` together with `useIndexModules: false`. This combination provides the best possible bundler optimizations. Use `dual` if CommonJS compatibility is required.
</Callout>

## Private field naming

```yml
typescript:
  privateIdentifierPrefix: "#"
```

## Import management

```yml
typescript:
  imports:
    option: "openapi"
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
```

### Import paths

## Error and response handling

```yml
typescript:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "union"
  fixEnumNameSanitization: false
  defaultErrorName: "SDKError"
  baseErrorName: "HTTPError"
  acceptHeaderEnum: false
```

## Model validation and serialization

```yml
typescript:
  jsonpath: "rfc9535"
  zodVersion: "v4-mini"
  constFieldsAlwaysOptional: false
  modelPropertyCasing: "camel"
  unionStrategy: "populated-fields"
  laxMode: "lax"
  alwaysIncludeInboundAndOutbound: false
  exportZodModelNamespace: false
```

## Forward compatibility

These options control how the SDK handles API evolution, allowing older SDK versions to continue working when APIs add new enum values, union types, or fields.

```yml
typescript:
  forwardCompatibleEnumsByDefault: true
  forwardCompatibleUnionsByDefault: tagged-only
```

<Callout title="Forward compatibility and fault tolerance" type="info">
These options work together with `laxMode` and `unionStrategy` to provide robust forward compatibility. When all four features are enabled (the default for new TypeScript SDKs), your SDK will gracefully handle API evolution including new enum values, new union types, missing fields, and type mismatches. See the [forward compatibility guide](/docs/sdks/manage/forward-compatibility) for more details.
</Callout>

## Server-sent events configuration

```yml
typescript:
  sseFlatResponse: false
```

## Build toolchain

These options update the TypeScript SDK build toolchain to use faster, modern build tools. Enabling both options can speed up generation time by up to 35% in GitHub Actions and locally.

```yml
typescript:
  useOxlint: true
  useTsgo: true
```

<Callout title="Generation speed optimization" type="info">
For fastest generation times, enable both `useOxlint` and `useTsgo` together. [OxLint](https://oxc.rs/docs/guide/usage/linter) replaces ESLint with a Rust-based linter that processes files in parallel, while [TSGo](https://github.com/microsoft/typescript-go) replaces `tsc` with a native Go compiler that delivers up to 10x faster type checking. Combined, these tools can reduce SDK generation time by up to 35%.
</Callout>

## Advanced features

```yml
typescript:
  enableReactQuery: false
  enableMCPServer: false
```