trigger-getting-started

First-time setup for Trigger.dev: sign in, add the packages and a settings file to a project that has none of it yet, and get one background job actually running.

WHEN TO USE

SCOPE

USE FOR

Add Trigger.dev to a project that has no trigger.config.ts yet.
Get a first task registered and running in the local dashboard.
Wire Trigger.dev into one app or package inside a monorepo.

NOT FOR

Writing the tasks themselves in depth — retries, waits, queues, scheduling — once setup is done.
Showing live run status in a frontend, or building an AI chat agent.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (8)

Getting started with Trigger.dev

Set up Trigger.dev in an existing project. The end state is: the SDK installed, a trigger.config.ts pointing at a project ref, a /trigger directory with at least one exported task, and trigger dev running so the task shows up in the dashboard.

The fastest path is the CLI's own wizard, which performs every mechanical step below and also offers to install the MCP server and these agent skills:

npx trigger.dev@latest init

Prefer init when you can. Do the manual steps further down when init does not fit (monorepos, an existing config to extend, or a non-interactive environment).

Two steps need the human

Most of setup is automatable, but two steps require a person and cannot be done headlessly. When you reach them, stop and ask the user to do them, then continue:

Authenticating the CLI. npx trigger.dev@latest login opens a browser for the user to sign in. If they have no account, point them to https://cloud.trigger.dev (or a self-hosted instance) first. You cannot complete this for them.
The environment API key and project ref. TRIGGER_SECRET_KEY and the project ref (proj_...) come from the dashboard. Ask the user to create a named API key with Trigger only access in their Development environment, and to pick or create the project so you have its ref. trigger init can select the project interactively once the user is logged in.

Treat these as handoffs: state exactly what you need, wait for the user, then resume.

Manual setup

1. Authenticate (human step)

npx trigger.dev@latest login
# self-hosted:
npx trigger.dev@latest login --api-url https://your-trigger-instance.com

2. Install the packages

@trigger.dev/sdk is a runtime dependency; @trigger.dev/build is a dev dependency. Pin both to the same version as the trigger.dev CLI you run; the CLI warns on a mismatch during dev/deploy.

npm add @trigger.dev/sdk@latest
npm add --save-dev @trigger.dev/build@latest

3. Write `trigger.config.ts`

Create it in the project root (or trigger.config.mjs for JavaScript). The project ref and dirs are the only required fields.

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

export default defineConfig({
  project: "<project ref>", // e.g. "proj_abc123", from the dashboard
  dirs: ["./src/trigger"], // where your tasks live
  maxDuration: 3600,
  retries: {
    enabledInDev: false,
    default: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000, maxTimeoutInMs: 10000, randomize: true },
  },
});

Use the Bun runtime by adding runtime: "bun". Build extensions (prismaExtension, puppeteer, additionalFiles, etc.) come from @trigger.dev/build and go in build.extensions.

4. Add a first task

Create the directory that matches dirs and export a task from it. Every task must be a named export with a project-unique id.

// src/trigger/example.ts
import { task } from "@trigger.dev/sdk";

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

5. Wire tsconfig and gitignore

Add trigger.config.ts to the include array in tsconfig.json, and add .trigger to .gitignore (the CLI writes local dev state there).

// tsconfig.json
{ "include": ["trigger.config.ts" /* ...existing */] }

# .gitignore
.trigger

6. Create an environment API key (human step)

For triggering from your own code, create a named API key with Trigger only access in your Development environment and set it as TRIGGER_SECRET_KEY. Self-hosted users also set TRIGGER_API_URL.

# .env (or .env.local for Next.js)
TRIGGER_SECRET_KEY=tr_dev_sk_xxxxxxxx

7. Run the dev server

npx trigger.dev@latest dev

Leave it running. Tasks register with the dashboard, where the user can fire a test run from the task's test page. On first run the CLI offers to install the MCP server and agent skills; recommend both.

Triggering from your app

Once a task exists, trigger it from backend code with a type-only import so the task code is never bundled into your app. Trigger by id, not by calling the task object.

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

const handle = await tasks.trigger<typeof helloWorld>("hello-world", { name: "Ada" });

TRIGGER_SECRET_KEY must be set wherever this runs. Framework specifics live in the Next.js / Remix / Node.js guides.

Monorepos

Two layouts, both supported: put tasks in a shared package (@repo/tasks with its own trigger.config.ts, consumed via workspace:*), or install Trigger.dev directly in the app that needs it. Run trigger dev from the directory that holds trigger.config.ts. See the manual setup docs for full Turborepo examples before scaffolding either.

Common mistakes

Trying to do the human-only steps headlessly. You cannot complete trigger login or create and copy an environment API key for the user.
- Wrong: spawning trigger login and waiting on it to finish in an agent session.
- Correct: ask the user to log in, create a named Development environment API key, and paste it, then continue.
Mismatched CLI and SDK versions. A trigger.dev CLI on a different major than @trigger.dev/sdk breaks dev/deploy.
- Wrong: npx trigger.dev@latest dev against an old pinned SDK.
- Correct: keep trigger.dev, @trigger.dev/sdk, and @trigger.dev/build on the same version.
Importing from @trigger.dev/sdk/v3 or using client.defineJob(). Both are old.
- Correct: always import from @trigger.dev/sdk; define work with task().
Tasks not exported, or outside dirs. A task that is not a named export inside a configured directory will not be picked up.
- Correct: export const ... = task({ ... }) in a file under a dirs path.
Importing the task instance into backend code. This bundles the task.
- Wrong: import { helloWorld } from "@/trigger/example" in a route handler.
- Correct: import type { helloWorld } plus tasks.trigger<typeof helloWorld>("hello-world", payload).
Forgetting TRIGGER_SECRET_KEY. Triggering from your app fails without it; the dev server itself works once the CLI is logged in.

References

Sibling skills:

trigger-authoring-tasks for writing the tasks themselves once setup is done: retries, waits, queues, scheduled tasks, triggering, and the full trigger.config.ts.
trigger-realtime-and-frontend for showing live run status in a frontend.
trigger-authoring-chat-agent and trigger-chat-agent-advanced for building AI chat agents.

Docs:

Version

Generated for @trigger.dev/sdk {{TRIGGER_SDK_VERSION}}. Re-run the trigger.dev skills installer after upgrading.

Account or credentials required

2 FOR YOU · 1 FOR THE AGENT

All items below are required.

01
Sign in to Trigger.dev from the CLI
Run npx trigger.dev@latest login (add --api-url for a self-hosted instance) so the user authenticates in a browser; point them to https://cloud.trigger.dev first if they have no account.
```
npx trigger.dev@latest login
```
02
Get a project ref and a Development API key
In the dashboard, create or pick a project to get its ref (proj_...), then create a named API key with Trigger-only access in the Development environment and set it as the secret key env var.
03
Install the SDK and build packages
Add @trigger.dev/sdk as a runtime dependency and @trigger.dev/build as a dev dependency, pinned to the same version as the trigger.dev CLI you run.

Not standalone. This skill ships with triggerdotdev/trigger.dev and only works together with that tool — install the tool first, then add this skill.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add triggerdotdev/trigger.dev --skill "trigger-getting-started" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Same repository

trigger-authoring-chat-agent
Author and run a durable AI chat agent with chat.agent from @trigger.dev/sdk/ai: the per-turn run loop, why you MUST take streamText from the run argument rather than importing it from ai, returning a StreamTextResult vs calling chat.pipe(), the two server actions (chat.createStartSessionAction + auth.createPublicToken), and wiring useChat to useTriggerChatTransport. Load this when building, modifying, or debugging a chat backend (the agent task or its lifecycle hooks) or its React transport, when declaring typed tools or custom data parts, or when migrating a plain AI SDK streamText route to chat.agent.Read full description
trigger-authoring-tasks
Covers writing backend Trigger.dev tasks with @trigger.dev/sdk: defining task() and schemaTask(), the run function and its ctx, retries, waits, queues and concurrency, idempotency keys, run metadata, logging, triggering other tasks (and the Result shape), scheduled/cron tasks, and the essentials of trigger.config.ts. Load this whenever you are authoring or editing code inside a /trigger directory, defining a task, or writing backend code that triggers tasks. Realtime/React hooks and AI chat are covered by separate skills.Read full description
trigger-chat-agent-advanced
Advanced and operational chat.agent capabilities for Trigger.dev, loaded on demand. Load this when working on the raw Sessions primitive (sessions / SessionHandle), a custom chat transport or the realtime wire protocol, durable sub-agents (AgentChat, chat.stream.writer), human-in-the-loop, steering, actions, background injection (chat.defer / chat.inject), fast starts (preload, Head Start via @trigger.dev/sdk/chat-server), context resilience (compaction, recovery boot, OOM, large payloads), chat.local run-scoped state, offline testing with mockChatAgent, or prerelease/version upgrades. For the everyday chat.agent({...}) definition and the useTriggerChatTransport happy path, use the trigger-authoring-chat-agent skill instead.Read full description
trigger-dev-tasks
Use this skill when writing, designing, or optimizing Trigger.dev background tasks and workflows. This includes creating reliable async tasks, implementing AI workflows, setting up scheduled jobs, structuring complex task hierarchies with subtasks, configuring build extensions for tools like ffmpeg or Puppeteer/Playwright, and handling task schemas with Zod validation.Read full description
trigger-realtime-and-frontend
Trigger.dev client/frontend surface: subscribe to runs in realtime (runs.subscribeToRun and the @trigger.dev/react-hooks hook useRealtimeRun), consume metadata and AI/text streams in React (useRealtimeStream), trigger tasks from the browser (useTaskTrigger, useRealtimeTaskTrigger), and mint scoped frontend credentials with auth.createPublicToken / auth.createTriggerPublicToken. Load when wiring a frontend (React/Next.js/Remix) or backend-for-frontend to show live run progress, status badges, token streams, trigger buttons, or wait-token approval UIs. NOT for writing the backend task itself (streams.define / metadata.set is trigger-authoring-tasks territory); this is the consumer side.Read full description

Getting started with Trigger.dev

Two steps need the human

Manual setup

1. Authenticate (human step)

2. Install the packages

3. Write trigger.config.ts

4. Add a first task

5. Wire tsconfig and gitignore

6. Create an environment API key (human step)

7. Run the dev server

Triggering from your app

Monorepos

Common mistakes

References

Version

Account or credentials required

More skills

trigger-authoring-chat-agent

trigger-authoring-tasks

trigger-chat-agent-advanced

trigger-dev-tasks

trigger-realtime-and-frontend

3. Write `trigger.config.ts`