ScalarScalar API

TypeScript

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 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 Required Default Value Description
additionalPackageJSON false {} Additional key/value pairs for the package.json 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 Required Default Value Description
dependencies false {} Additional production dependencies to include in the package.json.
devDependencies false {} Additional development dependencies to include in the package.json.
peerDependencies false {} Peer dependencies for compatibility.

Method and parameter management 

typescript:
  maxMethodParams: 3
  methodArguments: "require-security-and-request"
Name Required Default Value Description
maxMethodParams false 0 Maximum number of parameters before an input object is created. 0 means input objects are always used.
flatteningOrder false parameters-first or body-first Determines the ordering of method arguments when flattening parameters and body fields.
methodArguments false require-security-and-request Determines how arguments for SDK methods are generated.

Security configuration 

typescript:
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
Property Description Type Default
flattenGlobalSecurity Enables inline security credentials during SDK instantiation. Recommended: true 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 Required Default Value Description
useIndexModules false true Controls generation of index modules (index.ts). Setting to false improves tree-shaking and build performance by avoiding barrel files.
moduleFormat false commonjs Sets the module format to use when compiling the SDK (commonjs, esm, or dual). Using dual 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.

See the module format configuration guide and barrel files documentation for detailed information about these optimizations.

Import management 

typescript:
  imports:
    option: "openapi"
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
Field Required Default Value Description
option false "openapi" Defines the type of import strategy. Typically set to "openapi", 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 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: false
  responseFormat: "envelope-http"
  enumFormat: "union"
Property Description Type Default
responseFormat Defines how responses are structured. Options: envelope, envelope-http, or flat. string envelope-http
enumFormat Determines how enums are generated. Options: enum (TypeScript enums) or union (union types). string union
clientServerStatusCodesAsErrors Treats 4XX and 5XX status codes as errors. Set to false to treat them as normal responses. boolean true