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 .

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

Name	Required	Default Value	Description
additionalPackageJSON	false	{}	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.

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

Name	Required	Default Value	Description
additionalScripts	false	{}	Custom npm scripts to add to the file. Scripts with the same name as default scripts will override them.
generateExamples	false	true	Whether to generate example files in an examples directory demonstrating SDK usage.
compileCommand	false	N/A	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	false	N/A	The SDK initialization code to use in usage examples (e.g., ).
usageSDKInitImports	false	[]	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:

Default scripts are generated automatically based on SDK configuration:


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

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"
}

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

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

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:

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:

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

Property	Description	Type	Default
flattenGlobalSecurity	Enables inline security credentials during SDK instantiation. Recommended:	boolean	true
envVarPrefix	Sets a prefix for environment variables that allows users to configure global parameters and security.	string	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.

Name	Required	Default Value	Description
useIndexModules	false	true	Controls generation of index modules ( ). Setting to improves tree-shaking and build performance by avoiding barrel files.
moduleFormat	false	dual	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.

Field	Required	Default Value	Description
option	false	"openapi"	Defines the type of import strategy. Typically set to , indicating that the structure is based on the OpenAPI document.
paths	false	{}	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.

Component	Default Value	Description
callbacks	models/callbacks	The directory where callback models will be imported from.
errors	models/errors	The directory where error models will be imported from.
operations	models/operations	The directory where operation models (i.e., API endpoints) will be imported from.
shared	models/components	The directory for shared components, such as reusable schemas, and data models imported from the OpenAPI spec.
webhooks	models/webhooks	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

Property	Description	Type	Default
responseFormat	Defines how responses are structured. Options: , , or .	string	flat
enumFormat	Determines how enums are generated. Options: (TypeScript enums) or (union types).	string	union
clientServerStatusCodesAsErrors	Treats and status codes as errors. Set to to treat them as normal responses.	boolean	true
defaultErrorName	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.	string	SDKError
baseErrorName	The name of the base error class used for HTTP error responses. Must start with a capital letter and contain only letters and numbers.	string	HTTPError
acceptHeaderEnum	Whether to generate TypeScript enums for controlling the return content type of SDK methods when multiple accept types are available.	boolean	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:

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

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

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

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

Advanced features


typescript:
  enableReactQuery: false

Property

enableReactQuery

Description

Generate React hooks using TanStack Query.

Type

boolean

Default

false

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

Last updated on September 16, 2025