Getting started with Trigger.dev

​

Automatic setup

If you don’t already have a long-running Node.js server, you can use our CLI to get a new project up and running in just a few seconds:

npx create-trigger@latest

You’ll be asked to choose from one of our Templates, and if this is your first time we suggest trying the Hello World template:

​

Manual setup

You can easily add Trigger.dev to your existing project. This guide will walk you through the steps to get your first workflow running.

​

Installing @trigger.dev packages

In your existing project install the packages:

• npm

• pnpm

• yarn

npm install @trigger.dev/sdk zod

What do the packages do?

• @trigger.dev/sdk is required to use Trigger.dev, it allows you to define and run workflows.
• zod is used to define schemas. See our zod guide for more details.

​

Get your development API key

Go to trigger.dev and sign up or login to your account.

In the bottom-left corner of an Organization page you can find your API keys.

​

Creating your first workflow

Workflows are triggered by events. In this example, we have defined a custom event called user.created. We support many different types of events including webhooks, scheduled, and more coming soon.

import { Trigger, customEvent } from "@trigger.dev/sdk";
import { z } from "zod";

new Trigger({
  // Give your Trigger a stable ID
  id: "new-user",
  name: "New user",
  // For security, we recommend moving this api key to your .env / secrets file.
  // Our env variable is called TRIGGER_API_KEY
  apiKey: "<your_api_key>",
  // Trigger on a custom event, see https://docs.trigger.dev/triggers/custom-events
  on: customEvent({
    name: "user.created",
    // Use zod to verify event payload. See https://docs.trigger.dev/guides/zod
    schema: z.object({
      id: z.string(),
    }),
  }),
  // The run functions gets called once per "user.created" event
  run: async (event, ctx) => {
    // Event is the payload of the event, e.g. { id: "user_1234" }
    await ctx.logger.info("A new user has been created!", { event });
  },
}).listen(); // Calling listen() will connect to Trigger.dev and start listening for events

Make sure you import your trigger file in your server code, e.g. src/index.ts:

import "./triggers";

​

Start your Node.js process

Now that you have your workflow defined, you can start your Node.js process, usually this is done by running npm run dev or npm start, depending on your project.

Once you run your process, you should see a message in your console that looks like this:

[trigger.dev]  ✨ Connected and listening for events [new-user]

​

Trigger the workflow

You can use the @trigger.dev/sdk to send custom events which will trigger your workflow. In this example we are using the sendEvent function to send a user.created event:

import { sendEvent } from "@trigger.dev/sdk";
import { randomUUID } from "node:crypto";

// The first param should be a unique ID for this event
// You'll also need to set your development API key in the TRIGGER_API_KEY environment variable
await sendEvent(randomUUID(), {
  name: "user.created",
  payload: { id: "user_1234" },
});

To learn more about sending events, including using our API, see the Sending events guide.

​

Next steps

Explore the rest of our guides to learn more about how to use Trigger.dev

​

Guides

​

Triggers

Triggers are what cause your workflows to run.

​

Functions

​

Get help

Contact us if you have any questions, or would like help with any issues.