trigger.dev

Integrate trigger.dev with your TurboStarter application for reliable background task processing.

trigger.dev is an open-source background jobs framework that lets you write reliable workflows in plain async code.

Why trigger.dev?

trigger.dev provides automatic retries, real-time monitoring, and seamless scaling - all while letting you write background tasks in familiar JavaScript/TypeScript code directly in your TurboStarter project.

Setup

Visit trigger.dev and create a free account. Create a new project and note down your API key.

Add your trigger.dev API key to your root environment variables:

.env.local

TRIGGER_SECRET_KEY=your_secret_key_here

For production, make sure to add the production API key to your deployment environment.

Create a new package in your repository

You can use the Turbo generator to quickly scaffold the package structure:

turbo gen package

When prompted, name your package tasks. This will create the basic structure for you.

Alternatively, create a new folder tasks in the /packages directory and add the following files:

{
  "name": "@turbostarter/tasks",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "clean": "git clean -xdf .cache .turbo dist node_modules",
    "dev": "pnpm dlx trigger.dev@latest dev",
    "deploy": "pnpm dlx trigger.dev@latest deploy",
    "format": "prettier --check . --ignore-path ../../.gitignore",
    "lint": "eslint",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@trigger.dev/sdk": "3.3.17"
  },
  "devDependencies": {
    "@trigger.dev/build": "3.3.17",
    "@turbostarter/eslint-config": "workspace:*",
    "@turbostarter/prettier-config": "workspace:*",
    "@turbostarter/tsconfig": "workspace:*",
    "eslint": "catalog:",
    "prettier": "catalog:",
    "typescript": "catalog:"
  },
  "prettier": "@turbostarter/prettier-config"
}

{
  "extends": "@turbostarter/tsconfig/base.json",
  "include": ["**/*.ts"],
  "exclude": ["dist", "build", "node_modules"]
}

import { defineConfig } from "@trigger.dev/sdk/v3";

export default defineConfig({
  project: "your_project_id", // Replace with your actual project ID
  runtime: "node",
  logLevel: "log",
  maxDuration: 300,
  dirs: ["./src/trigger"],
});

Create your first task

Now create your first task in the packages/tasks/src/trigger directory:

packages/tasks/src/trigger/process-user-data.ts

import { task, logger, wait } from "@trigger.dev/sdk/v3";
import { z } from "zod";

const ProcessUserDataSchema = z.object({
  userId: z.string(),
  operation: z.enum(["export", "analyze", "cleanup"]),
});

export const processUserDataTask = task({
  id: "process-user-data",
  run: async (payload: z.infer<typeof ProcessUserDataSchema>) => {
    const { userId, operation } = payload;

    logger.info("Starting user data processing", { userId, operation });

    switch (operation) {
      case "export":
        await wait.for({ seconds: 2 });
        logger.info("User data exported successfully");
        return { success: true, result: "Data exported to CSV" };

      case "analyze":
        await wait.for({ seconds: 5 });
        logger.info("User data analysis completed");
        return {
          success: true,
          result: { totalActions: 156, avgSessionTime: "4m 32s" },
        };

      case "cleanup":
        await wait.for({ seconds: 3 });
        logger.info("User data cleanup completed");
        return { success: true, result: "Removed 23 obsolete records" };

      default:
        throw new Error(`Unknown operation: ${operation}`);
    }
  },
});

packages/tasks/src/trigger/daily-cleanup.ts

import { schedules, task, logger, wait } from "@trigger.dev/sdk/v3";

export const dailyCleanupTask = task({
  id: "daily-cleanup",
  run: async () => {
    logger.info("Starting daily cleanup");

    // Cleanup old logs
    await wait.for({ seconds: 5 });
    logger.info("Logs cleaned up");

    // Cleanup temporary files
    await wait.for({ seconds: 3 });
    logger.info("Temp files cleaned up");

    // Generate daily reports
    await wait.for({ seconds: 8 });
    logger.info("Reports generated");

    return {
      success: true,
      cleanupTime: new Date().toISOString(),
      itemsProcessed: 1247,
    };
  },
});

// Schedule the task to run daily at 2 AM
schedules.create({
  task: "daily-cleanup",
  cron: "0 2 * * *",
});

packages/tasks/src/index.ts

export * from "./trigger/process-user-data";
export * from "./trigger/daily-cleanup";

Test your task

You can test your tasks locally by running:

# Start the development server
pnpm --filter @turbostarter/tasks dev

This will deploy your tasks to trigger.dev in the development environment, allowing you to trigger them from the dashboard or programmatically.

Deploy your tasks

To deploy your tasks to production on trigger.dev, run:

pnpm --filter @turbostarter/tasks deploy

You can also add this command as an automated deployment step in your CI/CD pipeline by creating a new GitHub action.

Add the TRIGGER_ACCESS_TOKEN secret to your repository secrets, which you can create in the trigger.dev dashboard.

.github/workflows/deploy-tasks.yml

name: Deploy to trigger.dev (prod)

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - uses: pnpm/action-setup@v4
      - name: Install dependencies
        run: pnpm install
      - name: Deploy trigger tasks
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
        run: |
          pnpm --filter @turbostarter/tasks deploy

Triggering tasks

You can trigger tasks from your TurboStarter application using the API layer.

Direct task triggering not recommended

While you can trigger tasks directly from your frontend or server components using the trigger.dev SDK, it's recommended to use the API layer approach shown below.

This provides better security, validation, and separation of concerns.

First, add the @turbostarter/tasks package as a dependency to your API package:

packages/api/package.json

{
  "dependencies": {
    "@turbostarter/tasks": "workspace:*"
  }
}

From an API endpoint

Create a new API module to handle task triggering:

packages/api/src/modules/tasks/tasks.router.ts

import { tasks } from "@trigger.dev/sdk/v3";
import { Hono } from "hono";
import { z } from "zod";
import type { processUserDataTask } from "@turbostarter/tasks";

import { enforceAuth, validate } from "../../middleware";

const processUserDataSchema = z.object({
  userId: z.string(),
  operation: z.enum(["export", "analyze", "cleanup"]),
});

export const tasksRouter = new Hono().post(
  "/process-user-data",
  enforceAuth,
  validate("json", processUserDataSchema),
  async (c) => {
    const { userId, operation } = c.req.valid("json");

    const handle = await tasks.trigger<typeof processUserDataTask>(
      "process-user-data",
      { userId, operation },
    );

    return c.json({
      success: true,
      taskId: handle.id,
      message: "Background task started successfully",
    });
  },
);

Then register it in your main API router:

packages/api/src/index.ts

import { tasksRouter } from "./modules/tasks/tasks.router";

const appRouter = new Hono()
  .basePath("/api")
  .route("/tasks", tasksRouter)
  // ... other existing routers
  .onError(onError);

export { appRouter };

From the client

You can call the task endpoint from your web app using TurboStarter's API client:

apps/web/src/components/process-data-button.tsx

"use client";

import { handle } from "@turbostarter/api/utils";
import { useMutation } from "@tanstack/react-query";

import { api } from "~/lib/api/client";

export function ProcessDataButton({ userId }: { userId: string }) {
  const { mutate: processData, isPending } = useMutation({
    mutationFn: handle(api.tasks["process-user-data"].$post),
    onSuccess: (data) => {
      console.log("Task started:", data.taskId);
    },
  });

  return (
    <button
      onClick={() =>
        processData({
          json: { userId, operation: "analyze" },
        })
      }
      disabled={isPending}
    >
      {isPending ? "Processing..." : "Analyze User Data"}
    </button>
  );
}

From a server action

apps/web/src/app/actions/user-actions.ts

"use server";

import { handle } from "@turbostarter/api/utils";

import { api } from "~/lib/api/server";

export async function processUserData(userId: string, operation: string) {
  try {
    const result = await handle(api.tasks["process-user-data"].$post)({
      json: { userId, operation },
    });

    return {
      success: true,
      taskId: result.taskId,
    };
  } catch (error) {
    console.error("Failed to trigger background task:", error);
    throw new Error("Failed to start background task");
  }
}

Monitoring and debugging

Dashboard access

Visit the trigger.dev dashboard to monitor your tasks:

View task execution logs and performance metrics
Track success and failure rates across all your tasks
Monitor task duration and resource usage
Replay failed tasks with a single click
Set up alerts for task failures or performance issues

Local development

During development, run your tasks locally while connected to trigger.dev:

# Start everything in the workspace
pnpm dev

# or start the tasks package only
pnpm --filter @turbostarter/tasks dev

This allows you to:

Test tasks locally with real data
Debug with breakpoints and console logs
See immediate feedback as you develop

Best practices

Next steps

With trigger.dev integrated into your TurboStarter application, you can now:

Handle long-running operations that would timeout in serverless functions
Schedule recurring tasks like reports, cleanups, and maintenance
Process background jobs reliably with automatic retries
Scale your application without worrying about task execution infrastructure

Ready to explore more advanced features? Check out the official documentation for additional capabilities like webhooks, batching, and custom integrations.

Documentation

trigger.dev

Examples

trigger.dev

Use descriptive task IDs

Include proper error handling

Use structured logging

Keep tasks focused

Configure appropriate retries

Documentation

Examples

On this page