Create a blank project by running the create-next-app command in your terminal:

npx create-next-app@latest works with either the Pages or App Router configuration.

Installing Required Packages

To begin, install the necessary packages in your Next.js project directory. You can choose one of the following package managers:

npm i

Ensure that you execute this command within a Next.js project.

Obtaining the Development API Key

To locate your development API key, login to the dashboard and select the Project you want to connect to. Then click on the Environments & API Keys tab in the left menu. You can copy your development API Key from the field at the top of this page. (Your development key will start with tr_dev_).

Adding Environment Variables

Create a .env.local file at the root of your project and include your Trigger API key and URL like this:

TRIGGER_API_URL= # this is only necessary if you are self-hosting

Replace ENTER_YOUR_DEVELOPMENT_API_KEY_HERE with the actual API key obtained from the previous step.

Configuring the Trigger Client

Create a file at <root>/src/trigger.ts or <root>/trigger.ts depending on whether you’re using the src directory or not. <root> represents the root directory of your project.

Next, add the following code to the file which creates and exports a new TriggerClient:

// trigger.ts (for TypeScript) or trigger.js (for JavaScript)

import { TriggerClient } from "";

export const client = new TriggerClient({
  id: "my-app",
  apiKey: process.env.TRIGGER_API_KEY,
  apiUrl: process.env.TRIGGER_API_URL,

Replace “my-app” with an appropriate identifier for your project.

Creating the API Route

To establish an API route for interacting with, follow these steps based on your project’s file type and structure

  1. Create a new file named route.(ts/js) within the app/api/trigger/ directory.
  2. Add the following code to route.(ts/js):
import { createAppRoute } from "";
import { client } from "@/trigger";
import "@/Jobs";

export const { POST, dynamic } = createAppRoute(client);

In the code blocks, replace ”@/trigger” with the appropriate path to your Trigger Client configuration file, and adjust the path to the Jobs folder accordingly. Make sure to provide the correct paths if your project isn’t utilizing the Next.js alias feature.

Creating the Example Job

  1. Create a folder named Jobs alongside your app or pages directory
  2. Inside the Jobs folder, add two files named example.(ts/js) and index.(ts/js).
import { eventTrigger } from "";
import { client } from "@/trigger";

// your first job
  id: "example-job",
  name: "Example Job",
  version: "0.0.1",
  trigger: eventTrigger({
    name: "example.event",
  run: async (payload, io, ctx) => {
    await"Hello world!", { payload });

    return {
      message: "Hello world!",

Additonal Job Definitions

You can define more job definitions by creating additional files in the Jobs folder and exporting them in index file.

For example, in index.(ts/js), you can export other job files like this:

// import all your job files here

export * from "./examples";
export * from "./other-job-file";

Adding Configuration to package.json

Inside the package.json file, add the following configuration under the root object:

"": {
  "endpointId": "my-app"

Your package.json file might look something like this:

  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    // ... other dependencies
  "": {
    "endpointId": "my-app"

Replace “my-app” with the appropriate identifier you used during the step for creating the Trigger Client.


Run your Next.js app

Run your Next.js app locally, like you normally would. For example:

npm run dev

Run the CLI ‘dev’ command

In a separate terminal window or tab run:

npx dev

You can optionally pass the port if you’re not running on 3000 by adding --port 3001 to the end

You can optionally pass the hostname if you’re not running on localhost by adding --hostname <host>. Example, in case your Remix is running on --hostname

If your existing Next.js project utilizes middleware and you encounter any issues, such as potential conflicts with, it’s recommended to refer to the troubleshooting guide at Middleware for assistance. This guide can help you address any concerns related to middleware conflicts and ensure the smooth functioning of your project with