Authoring Trigger.dev Tasks

The full, version-pinned reference for authoring tasks ships inside your installed @trigger.dev/sdk. Read it before writing code — it always matches the SDK version in this project, so it never drifts:

• Skill: node_modules/@trigger.dev/sdk/skills/trigger-authoring-tasks/SKILL.md — the complete guide (setup, schemaTask, retries, triggering + the Result shape, idempotency, waits, metadata, scheduled tasks, queues/concurrency, trigger.config.ts).
• Docs: the full, version-pinned docs ship bundled at node_modules/@trigger.dev/sdk/docs/; the skill above lists the exact pages it draws from in its sources: frontmatter. Grep for an API, e.g. grep -rl "schemaTask" node_modules/@trigger.dev/sdk/docs/.

If those paths don't exist, @trigger.dev/sdk isn't installed yet — install it first. In a non-hoisted layout, resolve the package with node -p "require.resolve('@trigger.dev/sdk/package.json')" and read skills/ + docs/ beside it.

Always import from @trigger.dev/sdk — never @trigger.dev/sdk/v3 (deprecated alias) or @trigger.dev/core.

Common mistakes

1. CRITICAL: Treating the wait result as the output. triggerAndWait and wait.forToken return a Result object, not the raw output.

   • Wrong: const out = await childTask.triggerAndWait(p); use(out.foo);
   • Correct: const r = await childTask.triggerAndWait(p); if (r.ok) use(r.output.foo); (or .unwrap()).

2. Wrapping triggerAndWait / batchTriggerAndWait / wait in Promise.all.

   • Wrong: await Promise.all([childTask.triggerAndWait(a), childTask.triggerAndWait(b)]);
   • Correct: await childTask.batchTriggerAndWait([{ payload: a }, { payload: b }]); (or a sequential for-loop).

3. Importing the task instance into backend code.

   • Wrong: import { emailSequence } from "~/trigger/emails"; in a route handler.
   • Correct: import type { emailSequence } plus tasks.trigger<typeof emailSequence>("email-sequence", payload).

4. Calling metadata.set/get outside run().

   • Wrong: setting metadata at module scope or in unrelated backend code (a no-op; get returns undefined).
   • Correct: call inside run() or a task lifecycle hook.

5. Assuming child tasks inherit the parent's queue or metadata.

   • Wrong: expecting a subtask to share the parent's concurrencyLimit or see its metadata.
   • Correct: subtasks run on their own queue; pass metadata explicitly via { metadata: metadata.current() }, or push up with metadata.parent.*.

6. Bundling native/WASM packages.

   • Wrong: leaving sharp, re2, sqlite3, or WASM packages in the default bundle.
   • Correct: add them to build.external in trigger.config.ts.

7. Relying on a raw string idempotency key being global.

   • Wrong: trigger(p, { idempotencyKey: "welcome-email" }) expecting once-ever (true only in v4.3.0 and earlier).
   • Correct: await idempotencyKeys.create("welcome-email", { scope: "global" }).

References

Sibling skills: trigger-realtime-and-frontend (subscribe to runs, trigger from the frontend), trigger-authoring-chat-agent and trigger-chat-agent-advanced (AI chat agents).