# Source: https://trigger.dev/docs/manual-setup.md

> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual setup

> How to manually setup Trigger.dev in your project.

This guide covers how to manually set up Trigger.dev in your project, including configuration for different package managers, monorepos, and build extensions. This guide replicates all the steps performed by the `trigger.dev init` command. Follow our [Quickstart](/quick-start) for a more streamlined setup.

## Prerequisites

* Node.js 18.20+ (or Bun runtime)
* A Trigger.dev account (sign up at [trigger.dev](https://trigger.dev))
* TypeScript 5.0.4 or later (for TypeScript projects)

## CLI Authentication

Before setting up your project, you need to authenticate the CLI with Trigger.dev:

```bash  theme={"theme":"css-variables"}
# Login to Trigger.dev
npx trigger.dev@latest login

# Or with a specific API URL (for self-hosted instances)
npx trigger.dev@latest login --api-url https://your-trigger-instance.com
```

This will open your browser to authenticate. Once authenticated, you'll need to select or create a project in the Trigger.dev dashboard to get your project reference (e.g., `proj_abc123`).

## Package installation

Install the required packages based on your package manager:

<CodeGroup>
  ```bash npm theme={"theme":"css-variables"}
  npm add @trigger.dev/sdk@latest
  npm add --save-dev @trigger.dev/build@latest
  ```

  ```bash pnpm theme={"theme":"css-variables"}
  pnpm add @trigger.dev/sdk@latest
  pnpm add -D @trigger.dev/build@latest
  ```

  ```bash yarn theme={"theme":"css-variables"}
  yarn add @trigger.dev/sdk@latest
  yarn add -D @trigger.dev/build@latest
  ```

  ```bash bun theme={"theme":"css-variables"}
  bun add @trigger.dev/sdk@latest
  bun add -D @trigger.dev/build@latest
  ```
</CodeGroup>

## Environment variables

For local development, you need to set up the `TRIGGER_SECRET_KEY` environment variable. This key authenticates your application with Trigger.dev.

1. Go to your project dashboard in Trigger.dev
2. Navigate to the "API Keys" page
3. Copy the **DEV** secret key
4. Add it to your local environment file:

```bash  theme={"theme":"css-variables"}
TRIGGER_SECRET_KEY=tr_dev_xxxxxxxxxx
```

### Self-hosted instances

If you're using a self-hosted Trigger.dev instance, also set:

```bash  theme={"theme":"css-variables"}
TRIGGER_API_URL=https://your-trigger-instance.com
```

## CLI setup

You can run the Trigger.dev CLI in two ways:

### Option 1: Using npx/pnpm dlx/yarn dlx

```bash  theme={"theme":"css-variables"}
# npm
npx trigger.dev@latest dev

# pnpm
pnpm dlx trigger.dev@latest dev

# yarn
yarn dlx trigger.dev@latest dev
```

### Option 2: Add as dev dependency

Add the CLI to your `package.json`:

```json  theme={"theme":"css-variables"}
{
  "devDependencies": {
    "trigger.dev": "^4.0.0"
  }
}
```

Then add scripts to your `package.json`:

```json  theme={"theme":"css-variables"}
{
  "scripts": {
    "dev:trigger": "trigger dev",
    "deploy:trigger": "trigger deploy"
  }
}
```

### Version pinning

Make sure to pin the version of the CLI to the same version as the SDK that you are using:

```json  theme={"theme":"css-variables"}
"devDependencies": {
  "trigger.dev": "^4.0.0",
  "@trigger.dev/build": "^4.0.0"
},
"dependencies": {
  "@trigger.dev/sdk": "^4.0.0"
}
```

While running the CLI `dev` or `deploy` commands, the CLI will automatically detect mismatched versions and warn you.

## Configuration file

Create a `trigger.config.ts` file in your project root (or `trigger.config.mjs` for JavaScript projects):

```typescript  theme={"theme":"css-variables"}
import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  // Your project ref from the Trigger.dev dashboard
  project: "<your-project-ref>", // e.g., "proj_abc123"

  // Directories containing your tasks
  dirs: ["./src/trigger"], // Customize based on your project structure

  // Retry configuration
  retries: {
    enabledInDev: false, // Enable retries in development
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },

  // Build configuration (optional)
  build: {
    extensions: [], // Build extensions go here
  },

  // Max duration of a task in seconds
  maxDuration: 3600,
});
```

### Using the Bun runtime

By default, Trigger.dev will use the Node.js runtime. If you're using Bun, you can specify the runtime:

```typescript  theme={"theme":"css-variables"}
import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<your-project-ref>",
  runtime: "bun",
  dirs: ["./src/trigger"],
});
```

See our [Bun runtime documentation](/guides/frameworks/bun) for more information.

## Add your first task

Create a `trigger` directory (matching the `dirs` in your config) and add an example task:

```typescript src/trigger/example.ts theme={"theme":"css-variables"}
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { name: string }) => {
    console.log(`Hello ${payload.name}!`);

    return {
      message: `Hello ${payload.name}!`,
      timestamp: new Date().toISOString(),
    };
  },
});
```

See our [Tasks](/tasks/overview) docs for more information on how to create tasks.

## TypeScript config

If you're using TypeScript, add `trigger.config.ts` to your `tsconfig.json` include array:

```json  theme={"theme":"css-variables"}
{
  "compilerOptions": {
    // ... your existing options
  },
  "include": [
    // ... your existing includes
    "trigger.config.ts"
  ]
}
```

## Git config

Add `.trigger` to your `.gitignore` file to exclude Trigger.dev's local development files:

```bash  theme={"theme":"css-variables"}
# Trigger.dev
.trigger
```

If you don't have a `.gitignore` file, create one with this content.

## React hooks setup

If you're building a React frontend application and want to display task status in real-time, install the React hooks package:

### Installation

```bash  theme={"theme":"css-variables"}
# npm
npm install @trigger.dev/react-hooks@latest

# pnpm
pnpm add @trigger.dev/react-hooks@latest

# yarn
yarn add @trigger.dev/react-hooks@latest

# bun
bun add @trigger.dev/react-hooks@latest
```

### Basic usage

1. **Generate a Public Access Token** in your backend:

```typescript  theme={"theme":"css-variables"}
import { auth } from "@trigger.dev/sdk";

// In your backend API
export async function getPublicAccessToken() {
  const publicAccessToken = await auth.createPublicToken({
    scopes: ["read:runs"], // Customize based on needs
  });

  return publicAccessToken;
}
```

2. **Use hooks to monitor tasks**:

```tsx  theme={"theme":"css-variables"}
import { useRealtimeRun } from "@trigger.dev/react-hooks";

export function TaskStatus({
  runId,
  publicAccessToken,
}: {
  runId: string;
  publicAccessToken: string;
}) {
  const { run, error } = useRealtimeRun(runId, {
    accessToken: publicAccessToken,
  });

  if (error) return <div>Error: {error.message}</div>;
  if (!run) return <div>Loading...</div>;

  return (
    <div>
      <p>Status: {run.status}</p>
      <p>Progress: {run.completedAt ? "Complete" : "Running..."}</p>
    </div>
  );
}
```

For more information, see the [React Hooks documentation](/realtime/react-hooks/overview).

## Build extensions

Build extensions allow you to customize the build process. Ensure you have the `@trigger.dev/build` package installed in your project (see [package installation](#package-installation)).

Now you can use any of the built-in extensions:

```typescript  theme={"theme":"css-variables"}
import { defineConfig } from "@trigger.dev/sdk";
import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

export default defineConfig({
  project: "<project-ref>",
  build: {
    extensions: [
      prismaExtension({
        mode: "legacy",
        schema: "prisma/schema.prisma",
        migrate: true, // Run migrations on deploy
      }),
    ],
  },
});
```

See our [Build extensions](/config/extensions/overview) docs for more information on how to use build extensions and the available extensions.

## Monorepo setup

There are two main approaches for setting up Trigger.dev in a monorepo:

1. **Tasks as a package**: Create a separate package for your Trigger.dev tasks that can be shared across apps
2. **Tasks in apps**: Install Trigger.dev directly in individual apps that need background tasks

Both approaches work well depending on your needs. Use the tasks package approach if you want to share tasks across multiple applications, or the app-based approach if tasks are specific to individual apps.

### Approach 1: Tasks as a package (Turborepo)

This approach creates a dedicated tasks package that can be consumed by multiple apps in your monorepo.

#### 1. Set up workspace configuration

**Root `package.json`**:

```json  theme={"theme":"css-variables"}
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^2.4.4",
    "typescript": "5.8.2"
  },
  "packageManager": "pnpm@9.0.0"
}
```

**`pnpm-workspace.yaml`**:

```yaml  theme={"theme":"css-variables"}
packages:
  - "apps/*"
  - "packages/*"
```

**`turbo.json`**:

```json  theme={"theme":"css-variables"}
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^lint"]
    }
  }
}
```

#### 2. Create the tasks package

**`packages/tasks/package.json`**:

```json  theme={"theme":"css-variables"}
{
  "name": "@repo/tasks",
  "version": "0.0.0",
  "dependencies": {
    "@trigger.dev/sdk": "^4.0.0"
  },
  "devDependencies": {
    "@trigger.dev/build": "^4.0.0"
  },
  "exports": {
    ".": "./src/trigger/index.ts",
    "./trigger": "./src/index.ts"
  }
}
```

**`packages/tasks/trigger.config.ts`**:

```typescript  theme={"theme":"css-variables"}
import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<your-project-ref>", // Replace with your project reference
  dirs: ["./src/trigger"],
  retries: {
    enabledInDev: true,
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },
  maxDuration: 3600,
});
```

**`packages/tasks/src/index.ts`**:

```typescript  theme={"theme":"css-variables"}
export * from "@trigger.dev/sdk"; // Export values and types from the Trigger.dev sdk
```

**`packages/tasks/src/trigger/index.ts`**:

```typescript  theme={"theme":"css-variables"}
// Export tasks
export * from "./example";
```

**`packages/tasks/src/trigger/example.ts`**:

```typescript  theme={"theme":"css-variables"}
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { name: string }) => {
    console.log(`Hello ${payload.name}!`);

    return {
      message: `Hello ${payload.name}!`,
      timestamp: new Date().toISOString(),
    };
  },
});
```

See our [turborepo-prisma-tasks-package example](https://github.com/triggerdotdev/examples/tree/main/monorepos/turborepo-prisma-tasks-package) for a more complete example.

#### 3. Use tasks in your apps

**`apps/web/package.json`**:

```json  theme={"theme":"css-variables"}
{
  "name": "web",
  "dependencies": {
    "@repo/tasks": "workspace:*",
    "next": "^15.2.1",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}
```

**`apps/web/app/api/actions.ts`**:

```typescript  theme={"theme":"css-variables"}
"use server";

import { tasks } from "@repo/tasks/trigger";
import type { helloWorld } from "@repo/tasks";
//     👆 type only import

export async function triggerHelloWorld(name: string) {
  try {
    const handle = await tasks.trigger<typeof helloWorld>("hello-world", {
      name: name,
    });

    return handle.id;
  } catch (error) {
    console.error(error);
    return { error: "something went wrong" };
  }
}
```

#### 4. Development workflow

Run the development server for the tasks package:

```bash  theme={"theme":"css-variables"}
# From the root of your monorepo
cd packages/tasks
npx trigger.dev@latest dev

# Or using turbo (if you add dev:trigger script to tasks package.json)
turbo run dev:trigger --filter=@repo/tasks
```

### Approach 2: Tasks in apps (Turborepo)

This approach installs Trigger.dev directly in individual apps that need background tasks.

#### 1. Install in your app

**`apps/web/package.json`**:

```json  theme={"theme":"css-variables"}
{
  "name": "web",
  "dependencies": {
    "@trigger.dev/sdk": "^4.0.0",
    "next": "^15.2.1",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@trigger.dev/build": "^4.0.0"
  }
}
```

#### 2. Add configuration

**`apps/web/trigger.config.ts`**:

```typescript  theme={"theme":"css-variables"}
import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<your-project-ref>", // Replace with your project reference
  dirs: ["./src/trigger"],
  retries: {
    enabledInDev: true,
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },
  maxDuration: 3600,
});
```

#### 3. Create tasks

**`apps/web/src/trigger/example.ts`**:

```typescript  theme={"theme":"css-variables"}
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { name: string }) => {
    console.log(`Hello ${payload.name}!`);

    return {
      message: `Hello ${payload.name}!`,
      timestamp: new Date().toISOString(),
    };
  },
});
```

#### 4. Use tasks in your app

**`apps/web/app/api/actions.ts`**:

```typescript  theme={"theme":"css-variables"}
"use server";

import { tasks } from "@trigger.dev/sdk";
import type { helloWorld } from "../../src/trigger/example";
//     👆 type only import

export async function triggerHelloWorld(name: string) {
  try {
    const handle = await tasks.trigger<typeof helloWorld>("hello-world", {
      name: name,
    });

    return handle.id;
  } catch (error) {
    console.error(error);
    return { error: "something went wrong" };
  }
}
```

#### 5. Development workflow

```bash  theme={"theme":"css-variables"}
# From the app directory
cd apps/web
npx trigger.dev@latest dev

# Or from the root using turbo
turbo run dev:trigger --filter=web
```

## Example projects

You can find a growing list of example projects in our [examples](/guides/introduction) section.

## Troubleshooting

If you run into any issues, please check our [Troubleshooting](/troubleshooting) page.

## Feedback

If you have any feedback, please let us know by [opening an issue](https://github.com/triggerdotdev/trigger.dev/issues).