Skip to main content

TypeScript SDK introduction

The TypeScript SDK is Temporal's newest client SDK for developing with Temporal. It is designed with TypeScript-first developer experience in mind, but should work equally well with JavaScript.

For now, this SDK only works with Node.js 14 and 16+. Other JS/TS runtimes may be considered in future.

You can view:

Getting started#

You can run "Hello Temporal" locally in under 5 minutes.

Prerequisites
Node.js 14+: This project requires Node.js version 14 or later.

macOS users: Brew installation of Node.js versions 15.0 to 16.4 does not work with the SDK; instead install the latest Node.js version (16.4.1+) or use nvm

brew updatebrew upgrade node

-- OR --

nvm use 16

If you don’t have nvm (Node Version Manager), you can install it with:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bashnvm install 16nvm use 16
node-gyp: `npm install -g node-gyp`

Install node-gyp:

npm install -g node-gyp

You may have to install some system dependencies first as documented here.

node-gyp is a requirement of isolated-vm the V8 Isolate library which powers this SDK's deterministic runtime.

Temporal Server: make sure it is running locally!

Run Temporal Server (requires Docker and Docker Compose):

git clone https://github.com/temporalio/docker-compose.git temporalcd temporaldocker-compose up

If you want to run Temporal without Docker, DataDog has created an experimental project called temporalite you can try.

Step 1: Create a new project#

Use the package initializer to create a new project:

npx @temporalio/create@latest ./examplecd example

This will set up with the basic Hello World sample. If you want to start from a different sample, pass the --sample <sample-name> argument to the script. For example:

The list of official samples can be found in the samples-typescript repo.

note

npx triggers native module compilation which might take a while, npm 7 hides the compilation output so it may appear that the installation is stuck, to see the compilation progress export NPM_CONFIG_FOREGROUND_SCRIPTS=true.

Step 2: Run your Workflow#

Run the Worker:

# this runs ts-node src/worker.ts with nodemon to auto-reload on changes$ npm run start.watch
> temporal-hello-world@0.1.0 start.watch> nodemon src/worker.ts
[nodemon] 2.0.13[nodemon] to restart at any time, enter `rs`[nodemon] watching path(s): src/**/*[nodemon] watching extensions: ts[nodemon] starting `ts-node src/worker.ts`2021-10-14T00:31:39.875Z [INFO] [temporal_sdk_core] Registering worker task_queue="tutorial"2021-10-14T00:31:41.360Z [INFO] assets by path ./lib/*.map 605 bytes2021-10-14T00:31:41.360Z [INFO]   asset ./lib/workflows.d.ts.map 192 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/activities.d.ts.map 181 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/execute-workflow.d.ts.map 126 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/worker.d.ts.map 106 bytes [emitted]2021-10-14T00:31:41.360Z [INFO] assets by path ./lib/*.ts 357 bytes2021-10-14T00:31:41.360Z [INFO]   asset ./lib/workflows.d.ts 151 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/activities.d.ts 102 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/execute-workflow.d.ts 57 bytes [emitted]2021-10-14T00:31:41.360Z [INFO]   asset ./lib/worker.d.ts 47 bytes [emitted]2021-10-14T00:31:41.360Z [INFO] asset main.js 7.47 MiB [emitted] (name: main)2021-10-14T00:31:41.360Z [INFO] runtime modules 891 bytes 4 modules2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/ 2.92 MiB2021-10-14T00:31:41.360Z [INFO]   modules by path ./node_modules/@opentelemetry/api/build/esm/ 73.4 KiB 48 modules2021-10-14T00:31:41.360Z [INFO]   modules by path ./node_modules/@temporalio/ 2.74 MiB 31 modules2021-10-14T00:31:41.360Z [INFO]   modules by path ./node_modules/protobufjs/ 51.2 KiB2021-10-14T00:31:41.360Z [INFO]     modules by path ./node_modules/protobufjs/src/*.js 28.8 KiB 7 modules2021-10-14T00:31:41.360Z [INFO]     modules by path ./node_modules/protobufjs/src/util/*.js 17.7 KiB 2 modules2021-10-14T00:31:41.360Z [INFO]     2 modules2021-10-14T00:31:41.360Z [INFO]   modules by path ./node_modules/@protobufjs/ 23.7 KiB 7 modules2021-10-14T00:31:41.360Z [INFO]   ./node_modules/long/src/long.js 39.2 KiB [built] [code generated]2021-10-14T00:31:41.360Z [INFO]   ./node_modules/ms/index.js 2.95 KiB [built] [code generated]2021-10-14T00:31:41.360Z [INFO] ../../../../../src/main.js 462 bytes [built] [code generated]2021-10-14T00:31:41.360Z [INFO] ./src/workflows.ts 443 bytes [built] [code generated]2021-10-14T00:31:41.360Z [INFO] webpack 5.58.2 compiled successfully in 1293 ms2021-10-14T00:31:41.563Z [INFO] Worker state changed { state: 'RUNNING' }

If this step fails, make sure you have the correct version of Node and other prerequisites listed above.

Then start your Workflow:

$ npm run workflow # alias to ts-node src/exec-workflow.tsHello, Temporal!

This "Hello, Temporal!" message comes from the combination of:

  • execute-workflow.ts passing 'Temporal' as an argument to the Workflow.
  • The Workflow passing the argument to the Activity.
  • The Activity taking the argument as name and returning Hello, ${name}!.

You can verify this via the INPUT and RESULT fields in Temporal Web (available at localhost:8088 on the default docker-compose):

image

Next Steps#

For a full code walkthrough of the Hello World example that you have spun up here, see our Hello World documentation.

Then you should have a passing knowledge of our Core APIs:

  • Workflows and Activities: How to write Temporal's core orchestration code
    • see Workflow APIs for Signals, Queries, Timers, Child Workflows, Infinite Workflows, and more!
  • Workers and Task Queues: How Workflows and Activities are routed to and executed on machines you control
  • Clients: How to start, signal, query, cancel, or otherwise handle Workflows.

If you want an example of what it's like to integrate Temporal into an existing full-stack app, check our Next.js One-Click Buy Tutorial.