whyrating/.context/turbostarter-framework-context/sections/web/background-tasks/trigger.md

title, description, url

title	description	url
trigger.dev	Integrate trigger.dev with your TurboStarter application for reliable background task processing.	/docs/web/background-tasks/trigger

trigger.dev

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

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](https://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:

```dotenv title=".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](/docs/web/customization/add-package) to quickly scaffold the package structure:

```bash
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:

<Tabs items={["package.json", "tsconfig.json", "trigger.config.ts"]}>
  <Tab value="package.json">
    ```json
    {
      "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"
    }
    ```
  </Tab>

  <Tab value="tsconfig.json">
    ```json
    {
      "extends": "@turbostarter/tsconfig/base.json",
      "include": ["**/*.ts"],
      "exclude": ["dist", "build", "node_modules"]
    }
    ```
  </Tab>

  <Tab value="trigger.config.ts">
    ```ts
    import { defineConfig } from "@trigger.dev/sdk";

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

## Create your first task

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

<Tabs items={["process-user-data.ts", "daily-cleanup.ts", "src/index.ts"]}>
  <Tab value="process-user-data.ts">
    ```ts title="packages/tasks/src/trigger/process-user-data.ts"
    import { task, logger, wait } from "@trigger.dev/sdk";
    import * as 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}`);
        }
      },
    });
    ```
  </Tab>

  <Tab value="daily-cleanup.ts">
    ```ts title="packages/tasks/src/trigger/daily-cleanup.ts"
    import { schedules, task, logger, wait } from "@trigger.dev/sdk";

    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 * * *",
    });
    ```
  </Tab>

  <Tab value="src/index.ts">
    ```ts title="packages/tasks/src/index.ts"
    export * from "./trigger/process-user-data";
    export * from "./trigger/daily-cleanup";
    ```
  </Tab>
</Tabs>

## Test your task

You can test your tasks locally by running:

```bash
# 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:

```bash
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.

```yml title=".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.

<Callout type="warning" title="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.
</Callout>

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

```json title="packages/api/package.json"
{
  "dependencies": {
    "@turbostarter/tasks": "workspace:*"
  }
}
```

### From an API endpoint

Create a new API module to handle task triggering:

```ts title="packages/api/src/modules/tasks/tasks.router.ts"
import { tasks } from "@trigger.dev/sdk";
import { Hono } from "hono";
import * as 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:

```ts title="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:

```tsx title="apps/web/src/modules/tasks/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

```ts title="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

```ts // ✅ Good - Clear and descriptive id: "user-data-export-csv"; id: "weekly-newsletter-campaign"; id: "cleanup-temp-files";

// ❌ Not so good - Generic and unclear
id: "task1";
id: "job";
id: "process";
```

```ts run: async (payload) => { try { const result = await processData(payload); logger.info("Task completed successfully", { result }); return result; } catch (error) { logger.error("Task failed:", error.message); throw error; // Re-throw to trigger retry logic } }, ``` ```ts logger.info("Processing started", { userId: payload.userId, operation: payload.operation, timestamp: new Date().toISOString(), }); ``` Instead of one massive task, create focused, single-purpose tasks that can be composed together for complex workflows. Set retry policies based on your task's requirements:

```ts
// For critical operations
retry: {
  maxAttempts: 5,
  minTimeoutInMs: 2000,
  maxTimeoutInMs: 30000,
  factor: 2,
}

// For less critical operations
retry: {
  maxAttempts: 2,
  minTimeoutInMs: 1000,
  maxTimeoutInMs: 5000,
  factor: 1.5,
}
```

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.