Skip to main content

TypeScript SDK introduction

The Temporal TypeScript SDK (now in Beta) lets you write highly scalable and reliable long-running workflows without being a distributed systems expert. It is designed with TypeScript-first developer experience in mind, but works equally well with JavaScript.

You can view:

Getting started#

Choose your own adventure:

Run "Hello Temporal" in the cloud (~2 minutes)

Open our Samples repo in Gitpod and login to try out our Hello World example with no need for local Docker setup.

When you click on that link above and log in (there is a generous free tier), Gitpod will launch 4 terminals:

It takes ~3 minutes for the Docker Compose setup to start up. Once you have it up and running (Temporal Web should show the first Workflow Execution), you can use our Hello World Walkthrough tutorial to orient you to the sample file structure.

Run "Hello Temporal" locally (~10 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
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 using our Package Initializer (think of it like create-temporal-app!)

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
Expected Terminal Output
# 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/client.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/client.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 # runs ts-node src/exec-workflow.tsHello, Temporal! # success!

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

  • client.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}!.
Viewing your Workflow Execution in Temporal Web

You can verify execution in Temporal Web (available at localhost:8088 on the default docker-compose):

image

Next Steps#

For a full code walkthrough of our Hello World example, see our Hello World documentation.

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.

Read through the core API docs (~20 minutes)

These are the essential pages to have a passing knowledge of our Core APIs:

  • Workflows: How to write Temporal's core orchestration code
    • Workflows use Activities to act on the outside world (e.g. call an API with retries and timeouts, or access the filesystem)
    • 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.

TS SDK Intro Workshop#

We held a 2hr intro workshop for 80 people in Nov 2021:

And of course you can join the #typescript-sdk channel to ask any questions as you get set up. Design partners are already putting us in production and we are eager to hear your feedback.

Get notified of updates