@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/building-with-ai.mdx

@@ -0,0 +1,261 @@
+---
+title: "Overview"
+sidebarTitle: "Overview"
+description: "Tools and resources for building Trigger.dev projects with AI coding assistants."
+---
+
+## Quick setup
+
+We provide multiple tools to help AI coding assistants write correct Trigger.dev code. Use one or all of them for the best developer experience.
+
+
+<Steps>
+
+<Step title="Install the MCP Server">
+  Give your AI assistant direct access to Trigger.dev tools — search docs, trigger tasks, deploy projects, and monitor runs. Works with Claude Code, Cursor, Windsurf, VS Code (Copilot), and Zed.
+
+  ```bash
+  npx trigger.dev@latest install-mcp
+  ```
+
+  [Learn more →](/mcp-introduction)
+</Step>
+
+<Step title="Install Skills">
+  Portable instruction sets that teach any AI coding assistant Trigger.dev best practices: writing tasks, realtime frontends, and `chat.agent` AI agents. They install with the CLI into Claude Code, Cursor, VS Code (Copilot), and AGENTS-compatible tools such as Codex via `.agents/skills/`, and draw their API guidance from a version-pinned reference shipped in `@trigger.dev/sdk`.
+
+  ```bash
+  npx trigger.dev@latest skills
+  ```
+
+  [Learn more →](/skills)
+</Step>
+
+</Steps>
+
+## Skills and the MCP server
+
+Skills and the MCP server do different jobs and work best together. Here's how they compare:
+
+| | **Skills** | **MCP Server** |
+|:--|:-----------|:---------------|
+| **What it does** | Drops skill files into your project that teach Trigger.dev patterns | Runs a live server your AI connects to |
+| **Installs to** | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/` | `mcp.json`, `~/.claude.json`, etc. |
+| **Updates** | Re-run `npx trigger.dev@latest skills`, or auto-prompted on `trigger dev` | Always latest (uses `@latest`) |
+| **Best for** | Teaching patterns and best practices | Live project interaction (deploy, trigger, monitor) |
+| **Works offline** | Yes | No (calls Trigger.dev API) |
+
+**Our recommendation:** Install both. Skills teach your AI *how* to write Trigger.dev code; the MCP Server lets it *do things* in your project.
+
+## Project-level context snippet
+
+If you prefer a lightweight/passive approach, paste the snippet below into a context file at the root of your project. Different AI tools read different files:
+
+| File | Read by |
+|:-----|:--------|
+| `CLAUDE.md` | Claude Code |
+| `AGENTS.md` | OpenAI Codex, Jules, OpenCode |
+| `.cursor/rules/*.md` | Cursor |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `CONVENTIONS.md` | Windsurf, Cline, and others |
+
+Create the file that matches your AI tool (or multiple files if your team uses different tools) and paste the snippet below. This gives the AI essential Trigger.dev context without installing anything.
+
+<Accordion title="Copy the snippet">
+
+````markdown
+# Trigger.dev rules
+
+## Imports
+
+Always import from `@trigger.dev/sdk` — never from `@trigger.dev/sdk/v3` or use the deprecated `client.defineJob` pattern.
+
+## Task pattern
+
+Every task must be exported. Use `task()` from `@trigger.dev/sdk`:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 3,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+  },
+  run: async (payload: { url: string }) => {
+    // No timeouts — runs can take as long as needed
+    return { success: true };
+  },
+});
+```
+
+## Triggering tasks
+
+From your backend (Next.js route, Express handler, etc.):
+
+```ts
+import type { myTask } from "./trigger/my-task";
+import { tasks } from "@trigger.dev/sdk";
+
+// Fire and forget
+const handle = await tasks.trigger<typeof myTask>("my-task", { url: "https://example.com" });
+
+// Batch trigger (up to 1,000 items)
+const batchHandle = await tasks.batchTrigger<typeof myTask>("my-task", [
+  { payload: { url: "https://example.com/1" } },
+  { payload: { url: "https://example.com/2" } },
+]);
+```
+
+### From inside other tasks
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Fire and forget
+    await childTask.trigger({ data: "value" });
+
+    // Wait for result — returns a Result object, NOT the output directly
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log(result.output); // The actual return value
+    } else {
+      console.error(result.error);
+    }
+
+    // Or use .unwrap() to get output directly (throws on failure)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+  },
+});
+```
+
+> Never wrap `triggerAndWait` or `batchTriggerAndWait` in `Promise.all` — this is not supported.
+
+## Error handling
+
+```ts
+import { task, retry, AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const resilientTask = task({
+  id: "resilient-task",
+  retry: { maxAttempts: 5 },
+  run: async (payload) => {
+    // Permanent error — skip retrying
+    if (!payload.isValid) {
+      throw new AbortTaskRunError("Invalid payload, will not retry");
+    }
+
+    // Retry a specific block (not the whole task)
+    const data = await retry.onThrow(
+      async () => await fetchExternalApi(payload),
+      { maxAttempts: 3 }
+    );
+
+    return data;
+  },
+});
+```
+
+## Schema validation
+
+Use `schemaTask` with Zod for payload validation:
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const processVideo = schemaTask({
+  id: "process-video",
+  schema: z.object({ videoUrl: z.string().url() }),
+  run: async (payload) => {
+    // payload is typed and validated
+  },
+});
+```
+
+## Waits
+
+Use `wait.for` for delays, `wait.until` for dates, and `wait.forToken` for external callbacks:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+await wait.for({ seconds: 30 });
+await wait.until({ date: new Date("2025-01-01") });
+```
+
+## Configuration
+
+`trigger.config.ts` lives at the project root:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk/build";
+
+export default defineConfig({
+  project: "<your-project-ref>",
+  dirs: ["./trigger"],
+});
+```
+
+## Common mistakes
+
+1. **Forgetting to export tasks** — every task must be a named export
+2. **Importing from `@trigger.dev/sdk/v3`** — this is the old v3 path; always use `@trigger.dev/sdk`
+3. **Using `client.defineJob()`** — this is the deprecated v2 API
+4. **Calling `task.trigger()` directly** — use `tasks.trigger<typeof myTask>("task-id", payload)` from your backend
+5. **Using `triggerAndWait` result as output** — it returns a `Result` object; check `result.ok` then access `result.output`, or use `.unwrap()`
+6. **Wrapping waits/triggerAndWait in `Promise.all`** — not supported in Trigger.dev tasks
+7. **Adding timeouts to tasks** — tasks have no built-in timeout; use `maxDuration` in config if needed
+````
+
+</Accordion>
+
+## llms.txt
+
+We also publish machine-readable documentation for LLM consumption:
+
+- [trigger.dev/docs/llms.txt](https://trigger.dev/docs/llms.txt) — concise overview
+- [trigger.dev/docs/llms-full.txt](https://trigger.dev/docs/llms-full.txt) — full documentation
+
+These follow the [llms.txt standard](https://llmstxt.org) and can be fed directly into any LLM context window.
+
+
+## Troubleshooting
+
+<AccordionGroup>
+
+<Accordion title="AI keeps generating old v2/v3 code">
+  Install [Skills](/skills); they override the outdated patterns in the AI's training data. The [context snippet](#project-level-context-snippet) above is a quick alternative.
+</Accordion>
+
+<Accordion title="MCP server won't connect">
+  1. Make sure you've restarted your AI client after adding the config
+  2. Run `npx trigger.dev@latest install-mcp` again — it will detect and fix common issues
+  3. Check that `npx trigger.dev@latest mcp` runs without errors in your terminal
+  4. See the [MCP introduction](/mcp-introduction) for client-specific config details
+</Accordion>
+
+<Accordion title="Which tool should I install?">
+  Both if possible:
+  - **Skills** to teach your AI how to write Trigger.dev code (tasks, realtime, chat.agent)
+  - **MCP Server** if you need to trigger tasks, deploy, and search docs from your AI
+</Accordion>
+
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
+    Install and configure the MCP Server for live project interaction.
+  </Card>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/skills">
+    Install Trigger.dev agent skills into any AI coding assistant.
+  </Card>
+  <Card title="Writing tasks" icon="code" href="/tasks/overview">
+    Learn the task patterns your AI assistant will follow.
+  </Card>
+</CardGroup>

package/docs/bulk-actions.mdx

@@ -0,0 +1,49 @@
+---
+title: "Bulk actions"
+description: "Perform actions like replay and cancel on multiple runs at once."
+---
+
+Bulk actions allow you to perform replaying and canceling on multiple runs at once. This is especially useful when you need to retry a batch of failed runs with a new version of your code, or when you need to cancel multiple in-progress runs.
+
+<video
+  src="https://content.trigger.dev/bulk-actions.mp4"
+  preload="auto"
+  controls={true}
+  loop
+  muted
+  autoPlay={true}
+  width="100%"
+  height="100%"
+/>
+
+## How to create a new bulk action
+
+<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Open the bulk action panel from the top right of the runs page
+
+![Access bulk actions](/images/bulk-action-open-panel.png)
+
+
+<Icon icon="circle-2" iconType="solid" color="#FF2D6B" size="20" /> Filter the runs table to show the runs you want to bulk action
+
+<Icon icon="circle-3" iconType="solid" color="#FF2D6B" size="20" /> Alternatively, you can select individual runs
+
+<Icon icon="circle-4" iconType="solid" color="#FF2D6B" size="20" /> Choose the runs you want to bulk action
+
+<Icon icon="circle-5" iconType="solid" color="#FF2D6B" size="20" /> Name your bulk action (optional)
+
+<Icon icon="circle-6" iconType="solid" color="#FF2D6B" size="20" /> Choose the action you want to perform, replay or cancel
+
+<Icon icon="circle-7" iconType="solid" color="#FF2D6B" size="20" /> Click the "Replay" or "Cancel" button and confirm in the dialog
+
+![Access bulk actions](/images/bulk-action-create.png)
+
+<Icon icon="circle-8" iconType="solid" color="#FF2D6B" size="20" /> You'll now view the bulk action processing from the bulk action page
+
+<Icon icon="circle-9" iconType="solid" color="#FF2D6B" size="20" /> You can replay or view the runs from this page
+
+![Access bulk actions](/images/bulk-action-page.png)
+
+<Note>
+  You can only cancel runs that are in states that allow cancellation (like QUEUED or EXECUTING).
+  Runs that are already completed, failed, or in other final states by the time the bulk action process gets to them, cannot be canceled.
+</Note>

package/docs/changelog.mdx

@@ -0,0 +1,6 @@
+---
+title: "Changelog"
+url: "https://trigger.dev/changelog"
+---
+
+Our [changelog](https://trigger.dev/changelog) is the best way to stay up to date with the latest changes to Trigger.

package/docs/cli-deploy-commands.mdx

@@ -0,0 +1,9 @@
+---
+title: "CLI deploy command"
+sidebarTitle: "deploy"
+description: "Use the deploy command to deploy your tasks to Trigger.dev."
+---
+
+import CliDeployCommands from "/snippets/cli-commands-deploy.mdx";
+
+<CliDeployCommands />

package/docs/cli-dev-commands.mdx

@@ -0,0 +1,9 @@
+---
+title: "CLI dev command"
+sidebarTitle: "dev"
+description: "The `trigger.dev dev` command is used to run your tasks locally."
+---
+
+import CliDevCommands from "/snippets/cli-commands-develop.mdx";
+
+<CliDevCommands />

package/docs/cli-dev.mdx

@@ -0,0 +1,8 @@
+---
+title: "CLI dev command"
+description: "The `trigger.dev dev` command is used to run your tasks locally."
+---
+
+import CliDevCommands from "/snippets/cli-commands-develop.mdx";
+
+<CliDevCommands />

package/docs/cli-init-commands.mdx

@@ -0,0 +1,58 @@
+---
+title: "CLI init command"
+sidebarTitle: "init"
+description: "Use these options when running the CLI `init` command."
+---
+
+import CommonOptions from '/snippets/cli-options-common.mdx';
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest init
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest init
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest init
+```
+
+</CodeGroup>
+
+## Options
+
+<ParamField body="Javascript" type="--javascript">
+  By default, the init command assumes you are using TypeScript. Use this flag to initialize a
+  project that uses JavaScript.
+</ParamField>
+
+<ParamField body="Project ref" type="--project-ref | -p">
+  The project ref to use when initializing the project.
+</ParamField>
+
+<ParamField body="Package tag" type="--tag | -t">
+  The version of the `@trigger.dev/sdk` package to install. Defaults to `latest`.
+</ParamField>
+
+<ParamField body="Skip package install" type="--skip-package-install">
+  Skip installing the `@trigger.dev/sdk` package.
+</ParamField>
+
+<ParamField body="Override config" type="--override-config">
+  Override the existing config file if it exists.
+</ParamField>
+
+<ParamField body="Package arguments" type="--pkg-args">
+  Additional arguments to pass to the package manager. Accepts CSV for multiple args.
+</ParamField>
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-introduction.mdx

@@ -0,0 +1,25 @@
+---
+title: "Introduction"
+description: "The Trigger.dev CLI has a number of options and commands to help you develop locally, self host, and deploy your tasks."
+---
+
+import HelpOption from '/snippets/cli-options-help.mdx';
+import VersionOption from '/snippets/cli-options-version.mdx';
+
+## Options
+
+<HelpOption />
+<VersionOption />
+
+## Commands
+
+| Command                                      | Description                                                        |
+| :------------------------------------------- | :----------------------------------------------------------------- |
+| [login](/cli-login-commands)                 | Login with Trigger.dev so you can perform authenticated actions.   |
+| [init](/cli-init-commands)                   | Initialize your existing project for development with Trigger.dev. |
+| [dev](/cli-dev-commands)                     | Run your Trigger.dev tasks locally.                                |
+| [deploy](/cli-deploy-commands)               | Deploy your Trigger.dev v3 project to the cloud.                   |
+| [whoami](/cli-whoami-commands)               | Display the current logged in user and project details.            |
+| [logout](/cli-logout-commands)               | Logout of Trigger.dev.                                             |
+| [list-profiles](/cli-list-profiles-commands) | List all of your CLI profiles.                                     |
+| [update](/cli-update-commands)               | Updates all `@trigger.dev/*` packages to match the CLI version.    |

package/docs/cli-list-profiles-commands.mdx

@@ -0,0 +1,42 @@
+---
+title: "CLI list-profiles command"
+sidebarTitle: "list-profiles"
+description: "Use these options when using the `list-profiles` CLI command."
+---
+
+import LogLevelOption from "/snippets/cli-options-log-level.mdx";
+import SkipTelemetryOption from "/snippets/cli-options-skip-telemetry.mdx";
+import HelpOption from "/snippets/cli-options-help.mdx";
+import VersionOption from "/snippets/cli-options-version.mdx";
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest list-profiles
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest list-profiles
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest list-profiles
+```
+
+</CodeGroup>
+
+## Options
+
+### Common options
+
+These options are available on most commands.
+
+<LogLevelOption />
+
+<SkipTelemetryOption />
+
+<HelpOption />
+
+<VersionOption />

package/docs/cli-login-commands.mdx

@@ -0,0 +1,33 @@
+---
+title: "CLI login command"
+sidebarTitle: "login"
+description: "Use these options when logging in to Trigger.dev using the CLI."
+---
+
+import CommonOptions from '/snippets/cli-options-common.mdx';
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest login
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest login
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest login
+```
+
+</CodeGroup>
+
+## Options
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-logout-commands.mdx

@@ -0,0 +1,33 @@
+---
+title: "CLI logout command"
+sidebarTitle: "logout"
+description: "Use these options when using the `logout` CLI command."
+---
+
+import CommonOptions from '/snippets/cli-options-common.mdx';
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest logout
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest logout
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest logout
+```
+
+</CodeGroup>
+
+## Options
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-preview-archive.mdx

@@ -0,0 +1,59 @@
+---
+title: "CLI preview archive command"
+sidebarTitle: "preview archive"
+description: "The `trigger.dev preview archive` command can be used to archive a preview branch."
+---
+
+import ProjectPathArg from "/snippets/cli-args-project-path.mdx";
+import CommonOptions from "/snippets/cli-options-common.mdx";
+import ProjectRefOption from "/snippets/cli-options-project-ref.mdx";
+import EnvFileOption from "/snippets/cli-options-env-file.mdx";
+import ConfigFileOption from "/snippets/cli-options-config-file.mdx";
+import SkipUpdateCheckOption from "/snippets/cli-options-skip-update-check.mdx";
+import BranchOption from "/snippets/cli-options-branch.mdx";
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest preview archive
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest preview archive
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest preview archive
+```
+
+</CodeGroup>
+
+It will archive the preview branch, automatically detecting the branch name from git. You can manually specify the branch using the `--branch` option.
+
+## Arguments
+
+```
+npx trigger.dev@latest preview archive [path]
+```
+
+<ProjectPathArg />
+
+## Options
+
+<BranchOption />
+
+<ConfigFileOption />
+
+<ProjectRefOption />
+
+<EnvFileOption />
+
+<SkipUpdateCheckOption />
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-promote-commands.mdx

@@ -0,0 +1,9 @@
+---
+title: "CLI promote command"
+sidebarTitle: "promote"
+description: "Use the promote command to promote a previously deployed version to the current version."
+---
+
+import CliPromoteCommands from "/snippets/cli-commands-promote.mdx";
+
+<CliPromoteCommands />

package/docs/cli-switch.mdx

@@ -0,0 +1,43 @@
+---
+title: "CLI switch command"
+sidebarTitle: "switch"
+description: "The `trigger.dev switch` command can be used to switch between profiles."
+---
+
+import ProjectPathArg from "/snippets/cli-args-project-path.mdx";
+import CommonOptions from "/snippets/cli-options-common.mdx";
+import ProjectRefOption from "/snippets/cli-options-project-ref.mdx";
+import EnvFileOption from "/snippets/cli-options-env-file.mdx";
+import ConfigFileOption from "/snippets/cli-options-config-file.mdx";
+import SkipUpdateCheckOption from "/snippets/cli-options-skip-update-check.mdx";
+import BranchOption from "/snippets/cli-options-branch.mdx";
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest switch [profile]
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest switch [profile]
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest switch [profile]
+```
+
+</CodeGroup>
+
+It will switch to the specified profile. If no profile is specified, it will list all available profiles and run interactively.
+
+## Arguments
+
+```
+npx trigger.dev@latest switch [profile]
+```
+
+<ParamField body="Profile" type="[profile]">
+  The profile to switch to. If not specified, it will list all available profiles and run interactively.
+</ParamField>