Skip to main content

Hello World Walkthrough in TypeScript

In this tutorial, we'll go over the different components that make up a Temporal project. All of the code on this page is included in our Hello World sample, which we set up in our Getting Started (we recommend following along on GitPod).

The SDK steers developers to write their Workflows and Activities in TypeScript but vanilla JS is also supported.

Activity#

@temporalio/activity API reference

Activities are called from Workflows in order to run non-deterministic code.

Any async function can be used as an Activity as long as its parameters and return value are serializable. Activities run in the Node.js execution environment, meaning you can easily port over any existing code into an Activity and it should work.

src/activities.ts

export async function greet(name: string): Promise<string> {  return `Hello, ${name}!`;}

Workflow#

@temporalio/workflow API reference

In the TypeScript SDK, each Workflow execution is run in a separate V8 isolate context in order to provide a deterministic runtime.

A Workflow is also an async function, but it has access to special Workflow APIs like Signals, Queries, Timers, and Child Workflows.

The snippet below uses proxyActivities to create a function that, when called, schedules an Activity in the system.

src/workflows.ts

import { proxyActivities } from '@temporalio/workflow';// Only import the activity typesimport type * as activities from './activities';
const { greet } = proxyActivities<typeof activities>({  startToCloseTimeout: '1 minute',});
/** A workflow that simply calls an activity */export async function example(name: string): Promise<string> {  return await greet(name);}

Worker#

@temporalio/worker API reference

The Worker hosts Workflows and Activities, connects to Temporal Server, and continually polls a Task Queue for Commands coming from Clients (see below). See the list of WorkerOptions for customizing Worker creation.

src/worker.ts

import { Worker } from '@temporalio/worker';import * as activities from './activities';
async function run() {  // Step 1: Register Workflows and Activities with the Worker and connect to  // the Temporal server.  const worker = await Worker.create({    workflowsPath: require.resolve('./workflows'),    activities,    taskQueue: 'tutorial',  });  // Worker connects to localhost by default and uses console.error for logging.  // Customize the Worker by passing more options to create():  // https://typescript.temporal.io/api/classes/worker.Worker
  // If you need to configure server connection parameters, see the mTLS example:  // https://github.com/temporalio/samples-typescript/tree/main/hello-world-mtls
  // Step 2: Start accepting tasks on the `tutorial` queue  await worker.run();
  // You may create multiple Workers in a single process in order to poll on multiple task queues.}
run().catch((err) => {  console.error(err);  process.exit(1);});

Client#

@temporalio/client API reference

The WorkflowClient class is used to interact with existing Workflows or to start new ones.

It can be used in any Node.js process (for example, an Express web server) and is separate from the Worker.

src/exec-workflow.ts

import { Connection, WorkflowClient } from '@temporalio/client';import { example } from './workflows';
async function run() {  const connection = new Connection(); // Connect to localhost with default ConnectionOptions.  // In production, pass options to the Connection constructor to configure TLS and other settings.  // This is optional but we leave this here to remind you there is a gRPC connection being established.
  const client = new WorkflowClient(connection.service, {    // In production you will likely specify `namespace` here; it is 'default' if omitted  });
  // Invoke the `example` Workflow, only resolved when the workflow completes  const result = await client.execute(example, {    args: ['Temporal'], // type inference works! args: [name: string]    taskQueue: 'tutorial',    workflowId: 'my-business-id',  });  console.log(result); // Hello, Temporal!}
run().catch((err) => {  console.error(err);  process.exit(1);});

Testing#

There is no official test suite for Workflows and Activities yet.

  • Since Activities are async functions, they should be testable as long as you avoid using Context or are able to mock it.
  • You can test Workflows by running them with a WorkflowClient.
  • Check the SDK's own tests for more examples.

Next Steps#

You should now be familiar with the Hello World project, which is the main way we encourage scaffolding out new projects.

Two paths from here:

  • Go Full Stack: Integrate the manually-run Temporal Client scripts you have into an Express.js app, or serverless function. Our Next.js Tutorial should help show you how to integrate with the frontend, and give indications on how to deploy.
  • Learn More: Explore using Signals, Queries and Timers in our Subscription Workflow tutorial.

Get notified of updates