packages/cli-v3/skills/trigger-getting-started/SKILL.md
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).
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:
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.TRIGGER_SECRET_KEY and the project ref
(proj_...) come from the dashboard. Ask the user to copy the DEV secret key
from the project's API Keys page, 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.
npx trigger.dev@latest login
# self-hosted:
npx trigger.dev@latest login --api-url https://your-trigger-instance.com
@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
trigger.config.tsCreate 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.
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}!` };
},
});
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
For triggering from your own code, set TRIGGER_SECRET_KEY to the DEV key from the
dashboard's API Keys page. Self-hosted users also set TRIGGER_API_URL.
# .env (or .env.local for Next.js)
TRIGGER_SECRET_KEY=tr_dev_xxxxxxxx
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.
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.
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.
Trying to do the human-only steps headlessly. You cannot complete trigger login
or read the dashboard secret key for the user.
trigger login and waiting on it to finish in an agent session.Mismatched CLI and SDK versions. A trigger.dev CLI on a different major than
@trigger.dev/sdk breaks dev/deploy.
npx trigger.dev@latest dev against an old pinned SDK.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.
@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.
export const ... = task({ ... }) in a file under a dirs path.Importing the task instance into backend code. This bundles the task.
import { helloWorld } from "@/trigger/example" in a route handler.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.
Sibling skills:
trigger.config.ts.Docs:
Generated for @trigger.dev/sdk {{TRIGGER_SDK_VERSION}}. Re-run the trigger.dev skills installer after upgrading.