Skip to main content

TypeScript SDK introduction

The Temporal TypeScript SDK 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.

Introduction to Temporal

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`
2022-06-17T23:47:12.854Z [INFO] asset main.js 352 KiB [emitted] (name: main) 1 related asset
2022-06-17T23:47:12.855Z [INFO] runtime modules 2.03 KiB 5 modules
2022-06-17T23:47:12.855Z [INFO] modules by path ./packages/test/lib/workflows/*.js 91.7 KiB 95 modules
2022-06-17T23:47:12.855Z [INFO] modules by path ./packages/workflow/lib/*.js 90.9 KiB
2022-06-17T23:47:12.855Z [INFO]   ./packages/workflow/lib/worker-interface.js 11.2 KiB [built] [code generated]
2022-06-17T23:47:12.855Z [INFO]   + 10 modules
2022-06-17T23:47:12.855Z [INFO] modules by path ./packages/common/lib/ 46.9 KiB
2022-06-17T23:47:12.855Z [INFO]   modules by path ./packages/common/lib/converter/*.js 27 KiB 8 modules
2022-06-17T23:47:12.855Z [INFO]   modules by path ./packages/common/lib/*.js 19.9 KiB 2 modules
2022-06-17T23:47:12.855Z [INFO] modules by path ./packages/internal-workflow-common/lib/*.js 13.5 KiB
2022-06-17T23:47:12.855Z [INFO]   ./packages/internal-workflow-common/lib/index.js 1.3 KiB [built] [code generated]
2022-06-17T23:47:12.855Z [INFO]   + 9 modules
2022-06-17T23:47:12.855Z [INFO] modules by path ./node_modules/ 43.5 KiB
2022-06-17T23:47:12.855Z [INFO]   modules by path ./node_modules/ramda/src/ 1.42 KiB 3 modules
2022-06-17T23:47:12.855Z [INFO]   + 2 modules
2022-06-17T23:47:12.855Z [INFO] __temporal_custom_payload_converter (ignored) 15 bytes [built] [code generated]
2022-06-17T23:47:12.855Z [INFO] webpack 5.72.0 compiled successfully in 351 ms
2022-06-17T23:47:12.857Z [INFO] Workflow bundle created { size: '0.34MB' }
2022-06-17T23:47:12.987Z [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: https://www.youtube.com/watch?v=CeHSmv8oF_4

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.