Temporal is a distributed, scalable, durable, and highly available orchestration engine used to execute asynchronous, long-running business logic in a scalable and resilient way.

Temporal TypeScript SDK is the framework for authoring workflows and activities using either the TypeScript or JavaScript programming languages.

For documentation and samples, see:

• TypeScript Development Guide
• TypeScript Samples
• TypeScript API Reference
• General Temporal Documentation

Quick Start

Installation

To add Temporal TypeScript SDK packages to an existing JavaScript project, run:

(for client-level features, e.g. starting or interracting with Workflows)

# Or `pnpm add` or `yarn add`
npm install --save \
    @temporalio/client \
    @temporalio/common

(for worker-level features, including running Workflows, Activities and Nexus Operations)

# Or `pnpm add` or `yarn add`
npm install --save \
    @temporalio/worker \
    @temporalio/workflow \
    @temporalio/activity \
    @temporalio/common

All @temporalio/* packages in a project must have the same version number. This requirement is generally enforced by peer dependencies of the Temporal packages, but it may sometime require extra cares in complex monorepos.

Requirements

Note

The following requirements apply to the current git branch, and not necessarily what's released on NPM.

Node.js

The Temporal TypeScript SDK is officially supported on Node 18, 20, 22, and 24.

In line with Node.js' release policy, we recommend that production applications only use Node's Active LTS or Maintenance LTS releases.

Other JavaScript runtime environments

The @temporalio/client package is believed to work properly on most server-side JavaScript environments, including Bun, Deno, and Cloudflare Workers. Note however that we do not run regular tests of the SDK on any other JavaScript runtime environments, and therefore can't provide official support for such execution environments. Use at your own risk!

Worker-level features (i.e. running Workflows, Activities, and Nexus Operations) of the Temporal TypeScript SDK rely extensively on several Node-specific features, including:

• Node-API native modules - Required to load the Core SDK native library.
• Node's worker_threads module - Required to offload Workflow Tasks execution to a separate thread.
• Node's vm modules - Required to create isolated execution environments for Workflow Tasks (i.e. the "Workflow Sandbox").
• Node's AsyncLocalStorage API - Required to track the context of the currently executing Workflow, Activity, or Nexus Operation tasks.
• Node's async_hooks module - Required to track stack traces and catch unhandled promise rejections inside of Workflows.

Some Node-compatible runtimes provide partial support for these APIs, and some users have reported anecdotal success in running Worker-level features of the Temporal TypeScript SDK in such environments. However, given the lack of maturity of those compatibility layers, we strongly discourage running Temporal Workers in anything except authentic Node.js at this time.

Be assured that we will continue to monitor evolution of those alternative runtimes, and will consider extending support to more environments as their respective compatibility layers mature.

SDK Development

Prerequisites

To build the Temporal TypeScript SDK from source, you will need to have:

• Node.js (usage of a version manager, such as fnm or nvm, is recommended)
• Rust (i.e. cargo on the PATH)
• Protobuf Compiler (i.e. protoc on the PATH)
• This repository, cloned recursively

To run tests locally, you will need:

• A Temporal Server instance accessible from 127.0.0.1:7233 (e.g. using the Temporal CLI)

Building

With all prerequisites in place, run the following commands from the root of the repository:

pnpm install
pnpm build

Run pnpm rebuild to delete all generated files and rerun build.

Refer to our contributing guide for details on other build procedures, as well as hints on resolving frequent build time issues.

Testing

To run the SDK's regular test suite, execute the following command from the root of the repository:

pnpm test

Refer to our contributing guide for details on other testing procedures.

Code Formatting and Linting

To format and lint the code, execute the following commands from the root of the repository:

pnpm format
pnpm lint

Repository Structure

This monorepo contains the following packages:

Subfolder	Package
packages/client/	@temporalio/client
packages/worker/	@temporalio/worker
packages/workflow/	@temporalio/workflow
packages/activity/	@temporalio/activity
packages/testing/	@temporalio/testing
packages/common/	@temporalio/common
packages/proto/	@temporalio/proto
packages/interceptors-opentelemetry/	@temporalio/interceptors-opentelemetry
packages/test/	SDK internal tests
packages/create-project/	@temporalio/create
packages/docs/	API docs
packages/core-bridge/	@temporalio/core-bridge
packages/envconfig/	@temporalio/envconfig
packages/nyc-test-coverage/	@temporalio/nyc-test-coverage
packages/plugin/	@temporalio/plugin
packages/nexus/	@temporalio/nexus

Contributing

We welcome issues and pull requests!

Please read our contributing guide to learn about our development process, and how to propose bugfixes and improvements.

Thank you to everyone who has contributed to the Temporal TypeScript SDK 😃🙌