TypeScript is a first-class language for building integrations with the CLI.
zapier init
provide the
configuration needed to get started with TypeScript integrations. If you
are adding TypeScript support to an existing app, you can check the
Structure of a TS Integration section
below for more details information about compiler settings, using the
zapier-platform-core
library, and how to compose Triggers, Creates,
and Searches together with TypeScript.
As of the 17.4.0 Platform release, all authentication templates support the --language
flag on the zapier init
command, which can be set to typescript
or javascript
.
Note that all TypeScript templates now default to ESM.
For example, for Basic Auth:
./my-app
with the following structure,
and install the dependencies.
zapier scaffold
as needed.
zapier scaffold
will automatically detect you’re using TypeScript, and create the
correct code accordingly:
define
helper functions are important to wrap your App,
Triggers, Creates, Searches, and Input Field definitions.src/
directory and compiled to dist/
. The
root of the integration now becomes ./src/index.ts
.import
/export
syntax is used instead of Node’s
require
/module.exports
assignments.defineInputFields
helper function should be used to define the
inputs for all of Triggers, Creates, and Searches. This helper will
automatically infer the types of all of the input fields specified.
This looks like:
InferInputData
type can derive the shape of the input data from
input fields defined with defineInputFields
. This is useful because it
provides the correct types for the bundle.inputData
property to give
to the various perform
functions.
defineInputField
helper that can be used to define an input field.
These can be put somewhere in the src/
directory, and then imported by
the actions that need them.
true
.
bundle.inputData
will not have type
information for its sibling input fields. We recommend casting referenced
fields to their known types. For example above, note
inputData.useCustomSubject as boolean
.bundle.inputData
property. Input fields returned from input functions
are always considered optional, even if they have required: true
in
their definition, as they cannot be guaranteed to be present.
When fields cannot be known ahead of time, the input function can return
completely unknown input fields. This is useful when the input fields
are derived from data returned from an API. In this case, known inputs
are preserved, but the bundle.inputData
property will consider any
other properties as unknown
.
type
qualified imports. The
relevant operation
sections inside the define
helpers will inform
and enforce the correct type for the different perform functions. They
are:
PollingTriggerPerform
WebhookTriggerPerform
WebhookTriggerPerformList
WebhookTriggerPerformSubscribe
WebhookTriggerPerformUnsubscribe
CreatePerform
CreatePerformResume
SearchPerform
SearchPerformResume
inputData
property. These Perform types should use
satisfies XyzPerform<…>
to enforce the correct types but preserve the
return type information.
InferInputData
type can be
used:
bundle.inputData
property is now typed as the inferred input data
from the inputFields
array.
define
helper functions to provide deep type inference about
the application. These are:
defineApp()
– Main function for the top-level app.defineTrigger()
/defineCreate()
/defineSearch()
– For the
relevant actions in an integration.defineInputFields()
– Wraps an array of input field definitions to
simplify handling full typing information about the input fields.src/index.ts
src/index.ts
. It should import
its dependencies, and the default export remains as the Application
object. Wrapping it with defineApp
will help to check its structure.
Otherwise it’s a normal integration, and you register Auth, middleware,
hydrators, Triggers, Creates, and Searches all the same way!
src/authentication.ts
src/authentication.ts
. It uses a satisfies Authentication
constraint to check its structure, and does not use a define
helper.
src/middleware.ts
src/middleware.ts
,
that are typed as BeforeRequestMiddleware
or
AfterResponseMiddleware
types. They are registered in the same way as
in JavaScript integrations in /src/index.ts
.
src/triggers/pollingTrigger.ts
define
helper that is default export from the file.
src/tsconfig.json
tsconfig.json
file configures the TypeScript compiler. Below are
settings that are recommended for developing TypeScript integrations.