Speakeasy Logo
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
Default Value
0.0.1
Description
The current version of the SDK.
packageName
Required
true
Default Value
openapi
Description
The name of the npm package. See npm package guidelines .
author
Required
true
Default Value
Speakeasy
Description
The name of the author of the published package. See npm author field .

Additional JSON package

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

Additional dependencies

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

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
Default Value
{}
Description
Custom npm scripts to add to the
file. Scripts with the same name as default scripts will override them.
generateExamples
Required
false
Default Value
true
Description
Whether to generate example files in an examples directory demonstrating SDK usage.
compileCommand
Required
false
Default Value
N/A
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.
usageSDKInit
Required
false
Default Value
N/A
Description
The SDK initialization code to use in usage examples (e.g.,
).
usageSDKInitImports
Required
false
Default Value
[]
Description
Array of imports to add when
is configured. Each import should have
,
, and optionally
fields (options:
,
,
).

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
Default Value
0
Description
Maximum number of parameters before an input object is created.
means input objects are always used.
flatteningOrder
Required
false
Default Value
parameters-first
Description
Determines the ordering of method arguments when flattening parameters and body fields. Options:
or
.
methodArguments
Required
false
Default Value
infer-optional-args
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
.

Security configuration

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

Module management

typescript:
  moduleFormat: "dual"
  useIndexModules: true
Name
useIndexModules
Required
false
Default Value
true
Description
Controls generation of index modules (
). Setting to
improves tree-shaking and build performance by avoiding barrel files.
moduleFormat
Required
false
Default Value
dual
Description
Sets the module format to use when compiling the SDK. Options:
,
, or
. Using
provides optimal compatibility while enabling modern bundler optimizations.

Performance optimization

For optimal bundle size and tree-shaking performance in modern applications, we recommend using moduleFormat: "dual" together with useIndexModules: false. This combination ensures maximum compatibility while enabling the best possible bundler optimizations.

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
Default Value
"openapi"
Description
Defines the type of import strategy. Typically set to
, indicating that the structure is based on the OpenAPI document.
paths
Required
false
Default Value
{}
Description
Customizes where different parts of the SDK (e.g., callbacks, errors, and operations) will be imported from.

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
.
Type
string
Default
flat
enumFormat
Description
Determines how enums are generated. Options:
(TypeScript enums) or
(union types).
Type
string
Default
union
clientServerStatusCodesAsErrors
Description
Treats
and
status codes as errors. Set to
to treat them as normal responses.
Type
boolean
Default
true
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.
Type
string
Default
SDKError
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.
Type
string
Default
HTTPError
acceptHeaderEnum
Description
Whether to generate TypeScript enums for controlling the return content type of SDK methods when multiple accept types are available.
Type
boolean
Default
false

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.
Type
string
Default
rfc9535
zodVersion
Description
The version of Zod to use for schema validation. Options:
,
, or
.
Type
string
Default
v4-mini
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.
Type
boolean
Default
false
modelPropertyCasing
Description
Property naming convention to use. Options:
(converts to camelCase) or
(converts to snake_case).
Type
string
Default
camel
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).
Type
string
Default
populated-fields
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
.
Type
string
Default
lax
alwaysIncludeInboundAndOutbound
Description
Whether to always include both inbound and outbound schemas for all types regardless of usage.
Type
boolean
Default
false
exportZodModelNamespace
Description
Whether to export the deprecated
namespace containing
and
aliases.
Type
boolean
Default
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.

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.
Type
boolean
Default
true
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.
Type
string
Default
tagged-only

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.
Type
boolean
Default
false

Advanced features

typescript:
  enableReactQuery: false
Property
enableReactQuery
Description
Generate React hooks using TanStack Query.
Type
boolean
Default
false

Last updated on