Skip to Content
DocumentationSpeakeasyGeneration ConfigTypeScript Configuration

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

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

typescript:
  additionalPackageJSON:
    license: "MIT"
Name
additionalPackageJSON
Required
false
Description
Additional key/value pairs for the
file. Example: license, keywords, etc.
Default Value
{}

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
.
Default Value
{}
devDependencies
Required
false
Description
Additional development dependencies to include in the
.
Default Value
{}
peerDependencies
Required
false
Description
Peer dependencies for compatibility.
Default Value
{}

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
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.,
).
Default Value
N/A
usageSDKInitImports
Required
false
Description
Array of imports to add when
is configured. Each import should have
,
, and optionally
fields (options:
,
,
).
Default Value
[]

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

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.
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:
or
.
Default Value
parameters-first
methodArguments
Required
false
Description
Determines how arguments for SDK methods are generated. If set to
, the method argument will be optional when all parameters and the request body are optional. Options:
or
.
Default Value
infer-optional-args

Security configuration

typescript:
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
Property
flattenGlobalSecurity
Description
Enables inline security credentials during SDK instantiation. Recommended:
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

typescript:
  moduleFormat: "dual"
  useIndexModules: true
  legacyFileNaming: false
Name
useIndexModules
Required
false
Description
Controls generation of index modules (
). Setting to
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:
,
, or
. New SDKs default to
for modern module resolution. Existing SDKs default to
for backward compatibility.
Default Value
esm (new SDKs), dual (existing SDKs)
legacyFileNaming
Required
false
Description
When
, uses legacy file naming (camelCase/lowercase). When
, uses kebab-case (e.g.,
). New SDKs default to
(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.

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

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

typescript:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "union"
  defaultErrorName: "SDKError"
  baseErrorName: "HTTPError"
  acceptHeaderEnum: false
Property
responseFormat
Description
Defines how responses are structured. Options:
,
, or
.
Default
flat
Type
string
enumFormat
Description
Determines how enums are generated. Options:
(TypeScript enums) or
(union types).
Default
union
Type
string
clientServerStatusCodesAsErrors
Description
Treats
and
status codes as errors. Set to
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

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:
(deprecated) or
(recommended). The
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:
,
, or
.
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
(legacy behavior), all const fields are optional. When
(recommended), const fields respect the OpenAPI spec's required array.
Default
false
Type
boolean
modelPropertyCasing
Description
Property naming convention to use. Options:
(converts to camelCase) or
(converts to snake_case).
Default
camel
Type
string
unionStrategy
Description
Strategy for deserializing union types. Options:
(tries each type in order and returns the first valid match) or
(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
, 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
). Lax mode only applies to deserialization of responses. When
is enabled,
is automatically set to
. Options:
or
.
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
and
aliases.
Default
false
Type
boolean

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
, SDKs gracefully handle new enum values added by the API instead of rejecting the response. Individual enums can be controlled with
or
in the OpenAPI spec.
Default
true
Type
boolean
forwardCompatibleUnionsByDefault
Description
Controls whether discriminated unions accept unknown discriminator values. When set to
, SDKs capture unknown union variants in a type-safe way instead of failing deserialization. Individual unions can be controlled with
or
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

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

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 (
) 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

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
and use the standalone MCP server generation target (
) instead.
Default
false
Type
boolean

Last updated on