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.
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 temporal
cd temporal
docker-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 ./example
cd 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 bytes
2021-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 bytes
2021-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 modules
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/ 2.92 MiB
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/@opentelemetry/api/build/esm/ 73.4 KiB 48 modules
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/@temporalio/ 2.74 MiB 31 modules
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/protobufjs/ 51.2 KiB
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/protobufjs/src/*.js 28.8 KiB 7 modules
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/protobufjs/src/util/*.js 17.7 KiB 2 modules
2021-10-14T00:31:41.360Z [INFO] 2 modules
2021-10-14T00:31:41.360Z [INFO] modules by path ./node_modules/@protobufjs/ 23.7 KiB 7 modules
2021-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 ms
2021-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/client.ts
Hello, 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:8080 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.

Getting Help

For quick questions, we are always available on the Temporal Slack.

For long form/FAQs, please search and ask on the Temporal community forum instead.

TS SDK Intro Workshop

We held a 2-hour introduction workshop explaining every core concept from scratch:

Timestamps:

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.