Quickstart - Setup

Configure your local development environment to get started developing with Temporal.

Install Node.js

The TypeScript SDK requires Node.js 16 or later. Install Node.js via your package manager by following the official Node.js instructions.

The TypeScript SDK requires Node.js 16 or later.

Install Node.js via your package manager by following the official Node.js instructions.

Install the Temporal TypeScript SDK

You can create a new project with the Temporal SDK:

If you're creating a new project using npx @temporalio/create, the required SDK packages will be installed automatically.

To add Temporal to an existing project, install the required packages manually with npm install @temporalio/client @temporalio/worker @temporalio/workflow.

Next, you'll configure a local Temporal Service for development.

npx @temporalio/create@latest ./my-app

When prompted to select a sample, choose the hello-world sample.

Install Temporal CLI

The fastest way to get a development version of the Temporal Service running on your local machine is to use Temporal CLI.

Choose your operating system to install Temporal CLI.

macOS
Windows
Linux

Install the Temporal CLI using Homebrew:

brew install temporal

Download the Temporal CLI archive for your architecture:

Extract it and add temporal.exe to your PATH.

Download the Temporal CLI for your architecture:

Extract the archive and move the temporal binary into your PATH, for example:

sudo mv temporal /usr/local/bin

Start the development server

Once you've installed Temporal CLI and added it to your PATH, open a new Terminal window and run the following command.

This command starts a local Temporal Service. It starts the Web UI, creates the default Namespace, and uses an in-memory database.

The Temporal Service will be available on localhost:7233. The Temporal Web UI will be available at http://localhost:8233.

Leave the local Temporal Service running as you work through tutorials and other projects. You can stop the Temporal Service at any time by pressing CTRL+C.

Once you have everything installed, you're ready to build apps with Temporal on your local machine.

After installing, open a new Terminal window and start the development server:

temporal server start-dev

Change the Web UI port

The Temporal Web UI may be on a different port in some examples or tutorials. To change the port for the Web UI, use the --ui-port option when starting the server:

temporal server start-dev --ui-port 8080

The Temporal Web UI will now be available at http://localhost:8080.

Run Hello World: Test Your Installation

Now let's verify your setup is working by creating and running a complete Temporal application with both a Workflow and Activity.

This test will confirm that:

The Temporal TypeScript SDK is properly installed
Your local Temporal Service is running
You can successfully create and execute Workflows and Activities
The communication between components is functioning correctly

1. Create the Activity

Create an Activity file (activity.ts):

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

An Activity is a normal function or method that executes a single, well-defined action (either short or long running), which often involve interacting with the outside world, such as sending emails, making network requests, writing to a database, or calling an API, which are prone to failure. If an Activity fails, Temporal automatically retries it based on your configuration.

2. Create the Workflow

Create a Workflow file (workflows.ts):

import { proxyActivities } from '@temporalio/workflow';
// Only import the activity types
import 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);
}

Workflows orchestrate Activities and contain the application logic. Temporal Workflows are resilient. They can run and keep running for years, even if the underlying infrastructure fails. If the application itself crashes, Temporal will automatically recreate its pre-failure state so it can continue right where it left off.

3. Create and Run the Worker

Create a Worker file (worker.ts):

import { NativeConnection, Worker } from '@temporalio/worker';
import * as activities from './activities';

async function run() {
  // Step 1: Establish a connection with Temporal server.
  //
  // Worker code uses `@temporalio/worker.NativeConnection`.
  // (But in your application code it's `@temporalio/client.Connection`.)
  const connection = await NativeConnection.connect({
    address: 'localhost:7233',
    // TLS and gRPC metadata configuration goes here.
  });
  try {
    // Step 2: Register Workflows and Activities with the Worker.
    const worker = await Worker.create({
      connection,
      namespace: 'default',
      taskQueue: 'hello-world',
      // Workflows are registered using a path as they run in a separate JS context.
      workflowsPath: require.resolve('./workflows'),
      activities,
    });

    // Step 3: Start accepting tasks on the `hello-world` queue
    //
    // The worker runs until it encounters an unexpected error or the process receives a shutdown signal registered on
    // the SDK Runtime object.
    //
    // By default, worker logs are written via the Runtime logger to STDERR at INFO level.
    //
    // See https://typescript.temporal.io/api/classes/worker.Runtime#install to customize these defaults.
    await worker.run();
  } finally {
    // Close the connection once the worker has stopped
    await connection.close();
  }
}

run().catch((err) => {
  console.error(err);
  process.exit(1);
});

Run the Worker and keep this terminal running:

npm run start

With your Activity and Workflow defined, you need a Worker to execute them. A Worker polls a Task Queue, that you configure it to poll, looking for work to do. Once the Worker dequeues a Workflow or Activity task from the Task Queue, it then executes that task.

Workers are a crucial part of your Temporal application as they're what actually execute the tasks defined in your Workflows and Activities. For more information on Workers, see Understanding Temporal and a deep dive into Workers.

4. Execute the Workflow

Now that your Worker is running, it's time to start a Workflow Execution.

This final step will validate that everything is working correctly with your file labeled client.ts.

Create a separate file called client.ts.

import { Client, Connection } from '@temporalio/client';
import { nanoid } from 'nanoid';
import { example } from './workflows';

async function run() {
  // Connect to the default Server location
  const connection = await Connection.connect({ address: 'localhost:7233' });
  // In production, pass options to configure TLS and other settings:
  // {
  //   address: 'foo.bar.tmprl.cloud',
  //   tls: {}
  // }

  const client = new Client({
    connection,
    // namespace: 'foo.bar', // connects to 'default' namespace if not specified
  });

  const handle = await client.workflow.start(example, {
    taskQueue: 'hello-world',
    // type inference works! args: [name: string]
    args: ['Temporal'],
    // in practice, use a meaningful business ID, like customerId or transactionId
    workflowId: 'workflow-' + nanoid(),
  });
  console.log(`Started workflow ${handle.workflowId}`);

  // optional: wait for client result
  console.log(await handle.result()); // Hello, Temporal!
}

run().catch((err) => {
  console.error(err);
  process.exit(1);
});

Then run:

npm run workflow

Verify Success

If everything is working correctly, you should see:

Worker processing the workflow and activity
Output: Workflow result: Hello, Temporal!
Workflow Execution details in the Temporal Web UI

Additional details about Workflow Execution

Temporal clients are not explicitly closed.
To enable TLS, the tls option can be set to true or a Temporalio::Client::Connection::TLSOptions instance.
Calling client.workflow.start() and client.workflow.execute() send a command to Temporal Server to schedule a new Workflow Execution on the specified Task Queue.
If you started a Workflow with client.workflow.start(), you can choose to wait for the result anytime with handle.result().
Using a Workflow Handle isn't necessary with client.workflow.execute().

Next: Run your first Temporal Application

Learn how to create a basic Workflow and run it with the Temporal TypeScript SDK

→

Install Node.js​

Install the Temporal TypeScript SDK​

Install Temporal CLI​

Start the development server​

Change the Web UI port

Run Hello World: Test Your Installation​

1. Create the Activity​

2. Create the Workflow​

3. Create and Run the Worker​

4. Execute the Workflow​

Verify Success​