Skip to content
Platform Status

CLI

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

Section titled “Version and general configuration”
typescript:
  version: 1.2.3
  author: "Author Name"
  packageName: "custom-sdk"
Name
version
Required
true
Description
The current version of the SDK.
Default Value
0.0.1
packageName
Required
true
Description
The name of the npm package. See npm package guidelines.
Default Value
openapi
author
Required
true
Description
The name of the author of the published package. See npm author field.
Default Value
Speakeasy

Additional JSON package

Section titled “Additional JSON package”
typescript:
  additionalPackageJSON:
    license: "MIT"
Name
additionalPackageJSON
Required
false
Description
Additional key/value pairs for the package.json file. Example: license, keywords, etc.
Default Value
{}

Additional dependencies

Section titled “Additional dependencies”
typescript:
  additionalDependencies:
    dependencies:
      axios: "^0.21.0"
    devDependencies:
      typescript: "^4.0.0"
    peerDependencies:
      react: "^16.0.0"
Name
dependencies
Required
false
Description
Additional production dependencies to include in the package.json.
Default Value
{}
devDependencies
Required
false
Description
Additional development dependencies to include in the package.json.
Default Value
{}
peerDependencies
Required
false
Description
Peer dependencies for compatibility.
Default Value
{}

Package scripts and examples

Section titled “Package scripts and examples”
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"
Name
additionalScripts
Required
false
Description
Custom npm scripts to add to the package.json file. Scripts with the same name as default scripts will override them.
Default Value
{}
generateExamples
Required
false
Description
Whether to generate example files in an examples directory demonstrating SDK usage.
Default Value
true
compileCommand
Required
false
Description
The command to use for compiling the SDK. Must be an array where the first element is the command and the rest are arguments.
Default Value
N/A
usageSDKInit
Required
false
Description
The SDK initialization code to use in usage examples (e.g., new Petstore({})).
Default Value
N/A
usageSDKInitImports
Required
false
Description
Array of imports to add when usageSDKInit is configured. Each import should have package, import, and optionally type fields (options: typeImport, packageImport, aliasImport).
Default Value
[]

How scripts are merged

Section titled “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:
{
  "lint": "eslint --cache --max-warnings=0 src",
  "build": "tsc",
  "prepublishOnly": "npm run build"
}
  1. Test scripts are added if tests are enabled:
{
  "test": "vitest run src --reporter=junit --outputFile=.speakeasy/reports/tests.xml --reporter=default",
  "check": "npm run test && npm run lint"
}
  1. Additional scripts override defaults if they have the same name:
typescript:
  additionalScripts:
    build: "custom-build-command"  # Replaces default "tsc" build
    deploy: "npm publish"           # Adds new script
  1. Result in package.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

Section titled “Method and parameter management”
typescript:
  maxMethodParams: 3
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"
Name
maxMethodParams
Required
false
Description
Maximum number of parameters before an input object is created. 0 means input objects are always used.
Default Value
0
flatteningOrder
Required
false
Description
Determines the ordering of method arguments when flattening parameters and body fields. Options: parameters-first or body-first.
Default Value
parameters-first
methodArguments
Required
false
Description
Determines how arguments for SDK methods are generated. If set to infer-optional-args, the method argument will be optional when all parameters and the request body are optional. Options: infer-optional-args or require-security-and-request.
Default Value
infer-optional-args

Security configuration

Section titled “Security configuration”
typescript:
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
Property
flattenGlobalSecurity
Description
Enables inline security credentials during SDK instantiation. Recommended: true
Default
true
Type
boolean
envVarPrefix
Description
Sets a prefix for environment variables that allows users to configure global parameters and security.
Default
N/A
Type
string

Module management

Section titled “Module management”
typescript:
  moduleFormat: "dual"
  useIndexModules: true
  legacyFileNaming: false
Name
useIndexModules
Required
false
Description
Controls generation of index modules (index.ts). Setting to false improves tree-shaking and build performance by avoiding barrel files.
Default Value
true
moduleFormat
Required
false
Description
Sets the module format to use when compiling the SDK. Options: commonjs, esm, or dual. New SDKs default to esm for modern module resolution. Existing SDKs default to dual for backward compatibility.
Default Value
esm (new SDKs), dual (existing SDKs)
legacyFileNaming
Required
false
Description
When true, uses legacy file naming (camelCase/lowercase). When false, uses kebab-case (e.g., simple-object.ts). New SDKs default to false (kebab-case).
Default Value
false (new SDKs)

Performance optimization

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.

Private field naming

Section titled “Private field naming”
typescript:
  privateIdentifierPrefix: "#"
Property
privateIdentifierPrefix
Description
Prefix used for internal class fields and methods in the generated SDK (for example, this.#hooks, this.#httpClient). Defaults to # (ECMAScript hard-private fields). Set to _, __, $, or an empty string for strict TypeScript linters that reject hard-private fields (e.g., tsetse's TS21216 error emitted by ban-private-fields rule, or the equivalent no-restricted-syntax ESLint rule).
Default

Type
string

Import management

Section titled “Import management”
typescript:
  imports:
    option: "openapi"
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
Field
option
Required
false
Description
Defines the type of import strategy. Typically set to "openapi", indicating that the structure is based on the OpenAPI document.
Default Value
"openapi"
paths
Required
false
Description
Customizes where different parts of the SDK (e.g., callbacks, errors, and operations) will be imported from.
Default Value
{}

Import paths

Section titled “Import paths”
Component
callbacks
Default Value
models/callbacks
Description
The directory where callback models will be imported from.
errors
Default Value
models/errors
Description
The directory where error models will be imported from.
operations
Default Value
models/operations
Description
The directory where operation models (i.e., API endpoints) will be imported from.
shared
Default Value
models/components
Description
The directory for shared components, such as reusable schemas, and data models imported from the OpenAPI spec.
webhooks
Default Value
models/webhooks
Description
The directory for webhook models, if the SDK includes support for webhooks.

Error and response handling

Section titled “Error and response handling”
typescript:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "union"
  fixEnumNameSanitization: false
  defaultErrorName: "SDKError"
  baseErrorName: "HTTPError"
  acceptHeaderEnum: false
Property
responseFormat
Description
Defines how responses are structured. Options: envelope, envelope-http, or flat.
Default
flat
Type
string
enumFormat
Description
Determines how enums are generated. Options: enum (TypeScript enums) or union (union types).
Default
union
Type
string
fixEnumNameSanitization
Description
When true, custom enum names provided via x-speakeasy-enums are preserved exactly as written, with only illegal character sanitization applied. No PascalCase or other casing transformations are performed. Only affects enums with x-speakeasy-enums overrides.
Default
false
Type
boolean
clientServerStatusCodesAsErrors
Description
Treats 4XX and 5XX status codes as errors. Set to false to treat them as normal responses.
Default
true
Type
boolean
defaultErrorName
Description
The name of the fallback error class if no more specific error class is matched. Must start with a capital letter and contain only letters and numbers.
Default
SDKError
Type
string
baseErrorName
Description
The name of the base error class used for HTTP error responses. Must start with a capital letter and contain only letters and numbers.
Default
HTTPError
Type
string
acceptHeaderEnum
Description
Whether to generate TypeScript enums for controlling the return content type of SDK methods when multiple accept types are available.
Default
false
Type
boolean

Model validation and serialization

Section titled “Model validation and serialization”
typescript:
  jsonpath: "rfc9535"
  zodVersion: "v4-mini"
  constFieldsAlwaysOptional: false
  modelPropertyCasing: "camel"
  unionStrategy: "populated-fields"
  laxMode: "lax"
  alwaysIncludeInboundAndOutbound: false
  exportZodModelNamespace: false
Property
jsonpath
Description
Sets the JSONPath implementation to use. Options: legacy (deprecated) or rfc9535 (recommended). The rfc9535 option follows the JSONPath specification and should be preferred for new SDKs.
Default
rfc9535
Type
string
zodVersion
Description
The version of Zod to use for schema validation. Options: v3, v4, or v4-mini.
Default
v4-mini
Type
string
constFieldsAlwaysOptional
Description
Whether const fields should be treated as optional in TypeScript types and schemas regardless of OpenAPI spec requirements. When true (legacy behavior), all const fields are optional. When false (recommended), const fields respect the OpenAPI spec's required array.
Default
false
Type
boolean
modelPropertyCasing
Description
Property naming convention to use. Options: camel (converts to camelCase) or snake (converts to snake_case).
Default
camel
Type
string
unionStrategy
Description
Strategy for deserializing union types. Options: left-to-right (tries each type in order and returns the first valid match) or populated-fields (tries all types and returns the one with the most matching fields, including optional fields).
Default
populated-fields
Type
string
laxMode
Description
Controls validation strictness. When set to lax, required fields will be coerced to their zero value (e.g., a missing required string will fallback to ""). Lax mode also applies other coercions (e.g., boolean schemas will accept the string "true"). Lax mode only applies to deserialization of responses. When laxMode is enabled, unionStrategy is automatically set to populated-fields. Options: lax or strict.
Default
lax
Type
string
alwaysIncludeInboundAndOutbound
Description
Whether to always include both inbound and outbound schemas for all types regardless of usage.
Default
false
Type
boolean
exportZodModelNamespace
Description
Whether to export the deprecated $ namespace containing inboundSchema and outboundSchema aliases.
Default
false
Type
boolean

Forward compatibility

Section titled “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.

typescript:
  forwardCompatibleEnumsByDefault: true
  forwardCompatibleUnionsByDefault: tagged-only
Property
forwardCompatibleEnumsByDefault
Description
Controls whether enums used in responses are treated as open enums that accept unknown values. When true, SDKs gracefully handle new enum values added by the API instead of rejecting the response. Individual enums can be controlled with x-speakeasy-unknown-values: allow or x-speakeasy-unknown-values: disallow in the OpenAPI spec.
Default
true
Type
boolean
forwardCompatibleUnionsByDefault
Description
Controls whether discriminated unions accept unknown discriminator values. When set to tagged-only, SDKs capture unknown union variants in a type-safe way instead of failing deserialization. Individual unions can be controlled with x-speakeasy-unknown-values: allow or x-speakeasy-unknown-values: disallow in the OpenAPI spec.
Default
tagged-only
Type
string

Forward compatibility and fault tolerance

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 for more details.

Server-sent events configuration

Section titled “Server-sent events configuration”
typescript:
  sseFlatResponse: false
Property
sseFlatResponse
Description
Whether to flatten SSE (Server-Sent Events) responses by extracting the data field from wrapper models, providing direct access to the event data instead of the wrapper object.
Default
false
Type
boolean

Build toolchain

Section titled “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.

typescript:
  useOxlint: true
  useTsgo: true
Property
useOxlint
Description
Replace ESLint with OxLint, a Rust-based linter that is 50-100x faster. When enabled, the generated SDK uses OxLint for linting instead of ESLint, significantly reducing lint times in CI and local development.
Default
true (new SDKs), false (existing SDKs)
Type
boolean
useTsgo
Description
Replace the standard TypeScript compiler (tsc) with TSGo, Microsoft's native Go-based TypeScript compiler. When enabled, the generated SDK uses TSGo for type checking and compilation, delivering up to 10x faster build times with lower memory usage.
Default
true (new SDKs), false (existing SDKs)
Type
boolean

Generation speed optimization

For fastest generation times, enable both useOxlint and useTsgo together. OxLint replaces ESLint with a Rust-based linter that processes files in parallel, while TSGo 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%.

Advanced features

Section titled “Advanced features”
typescript:
  enableReactQuery: false
  enableMCPServer: false
Property
enableReactQuery
Description
Generate React hooks using TanStack Query.
Default
false
Type
boolean
enableMCPServer
Description
Deprecated. Previously used to generate an MCP server as part of the TypeScript SDK. Users should leave this set to false and use the standalone MCP server generation target (mcp-typescript) instead.
Default
false
Type
boolean