diff --git a/docs/building-with-ai.mdx b/docs/building-with-ai.mdx index ba8cd5bb47..e551324cad 100644 --- a/docs/building-with-ai.mdx +++ b/docs/building-with-ai.mdx @@ -4,21 +4,272 @@ sidebarTitle: "Overview" description: "Tools and resources for building Trigger.dev projects with AI coding assistants." --- -We provide tools to help you build Trigger.dev projects with AI coding assistants. We recommend using them for the best developer experience. +## Quick setup - - - Give your AI assistant direct access to Trigger.dev tools - search docs, trigger tasks, deploy projects, and monitor runs. +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. + + + + + + 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) + + + + Portable instruction sets that teach any AI coding assistant Trigger.dev best practices. Works with Claude Code, Cursor, Windsurf, VS Code (Copilot), and any tool that supports the [Agent Skills standard](https://agentskills.io). + + ```bash + npx skills add triggerdotdev/skills + ``` + + [Learn more →](/skills) + + + + Comprehensive rule sets installed directly into your AI client's config files. Works with Cursor, Claude Code, VS Code (Copilot), Windsurf, Gemini CLI, Cline, and more. Claude Code also gets a dedicated subagent for hands-on help. + + ```bash + npx trigger.dev@latest install-rules + ``` + + [Learn more →](/mcp-agent-rules) + + + + +## Skills vs Agent Rules vs MCP + +Not sure which tool to use? Here's how they compare: + +| | **Skills** | **Agent Rules** | **MCP Server** | +|:--|:-----------|:----------------|:---------------| +| **What it does** | Drops skill files into your project | Installs rule sets into client config | Runs a live server your AI connects to | +| **Installs to** | `.claude/skills/`, `.cursor/skills/`, etc. | `.cursor/rules/`, `CLAUDE.md`, `AGENTS.md`, etc. | `mcp.json`, `~/.claude.json`, etc. | +| **Updates** | Re-run `npx skills add` | Re-run `npx trigger.dev@latest install-rules` or auto-prompted on `trigger dev` | Always latest (uses `@latest`) | +| **Best for** | Teaching patterns and best practices | Comprehensive code generation guidance | Live project interaction (deploy, trigger, monitor) | +| **Works offline** | Yes | Yes | No (calls Trigger.dev API) | + +**Our recommendation:** Install all three. Skills and Agent Rules teach your AI *how* to write 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. + + + +````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("my-task", { url: "https://example.com" }); + +// Batch trigger (up to 1,000 items) +const batchHandle = await tasks.batchTrigger("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); + } - ```bash - npx trigger.dev@latest install-mcp - ``` + // 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: "", + 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("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 +```` + + + +## 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 + + + + + Install [Agent Rules](/mcp-agent-rules) or [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. + + + + 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 + + + + All three if possible. If you can only pick one: + - **Agent Rules** if you want the broadest code generation improvement + - **Skills** if you use multiple AI tools and want a single install + - **MCP Server** if you need to trigger tasks, deploy, and search docs from your AI + + + + +## Next steps + + + + Install and configure the MCP Server for live project interaction. - Portable instruction sets that teach any AI coding assistant Trigger.dev best practices for writing tasks, configs, and more. - - ```bash - npx skills add triggerdotdev/skills - ``` + Portable instruction sets for any AI coding assistant. + + + Comprehensive rule sets installed into your AI client. + + + Learn the task patterns your AI assistant will follow. diff --git a/docs/docs.json b/docs/docs.json index 324052905a..4ec2fafc0e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -49,9 +49,10 @@ "building-with-ai", { "group": "MCP Server", - "pages": ["mcp-introduction", "mcp-tools", "mcp-agent-rules"] + "pages": ["mcp-introduction", "mcp-tools"] }, - "skills" + "skills", + "mcp-agent-rules" ] }, { diff --git a/docs/mcp-agent-rules.mdx b/docs/mcp-agent-rules.mdx index 321f312a84..d9ba021b89 100644 --- a/docs/mcp-agent-rules.mdx +++ b/docs/mcp-agent-rules.mdx @@ -1,13 +1,17 @@ --- title: "Agent rules" sidebarTitle: "Agent rules" -description: "Learn how to use the Trigger.dev agent rules with the MCP server" +description: "Install Trigger.dev agent rules to guide AI assistants toward correct, up-to-date code patterns." --- ## What are Trigger.dev agent rules? Trigger.dev agent rules are comprehensive instruction sets that guide AI assistants to write optimal Trigger.dev code. These rules ensure your AI assistant understands best practices, current APIs, and recommended patterns when working with Trigger.dev projects. + + Agent Rules are one of three AI tools we provide. You can also install [Skills](/skills) for portable cross-editor instruction sets or the [MCP Server](/mcp-introduction) for live project interaction. See the [comparison table](/building-with-ai#skills-vs-agent-rules-vs-mcp) for details. + + ## Installation Install the agent rules with the following command: @@ -112,6 +116,17 @@ npx trigger.dev@latest install-rules ## Next steps -- [Install the MCP server](/mcp-introduction) for complete Trigger.dev integration -- [Explore MCP tools](/mcp-tools) for project management and task execution - + + + Portable instruction sets that work across all AI coding assistants. + + + Give your AI assistant direct access to Trigger.dev tools and APIs. + + + See all AI tools and how they compare. + + + Learn the task patterns that agent rules teach your AI assistant. + + diff --git a/docs/mcp-introduction.mdx b/docs/mcp-introduction.mdx index 257522d579..a00f3dda89 100644 --- a/docs/mcp-introduction.mdx +++ b/docs/mcp-introduction.mdx @@ -361,4 +361,14 @@ Once installed, you can start using the MCP server by asking your AI assistant q ## Next Steps -- [Explore available MCP tools](/mcp-tools) + + + Explore all available MCP tools for managing your projects. + + + Portable instruction sets that teach AI assistants Trigger.dev patterns. + + + Install comprehensive rule sets directly into your AI client. + + diff --git a/docs/mcp-tools.mdx b/docs/mcp-tools.mdx index 058a3671ab..fdcdb56f3d 100644 --- a/docs/mcp-tools.mdx +++ b/docs/mcp-tools.mdx @@ -11,9 +11,9 @@ description: "Learn about how to use the tools available in the Trigger.dev MCP Search the Trigger.dev documentation for guides, examples, and API references. **Example usage:** -- _"How do I create a scheduled task?"_ -- _"Show me webhook examples"_ -- _"What are the deployment options?"_ +- `"How do I create a scheduled task?"` +- `"Show me webhook examples"` +- `"What are the deployment options?"` ## Project Management Tools @@ -22,32 +22,32 @@ Search the Trigger.dev documentation for guides, examples, and API references. List all organizations you have access to. **Example usage:** -- _"What organizations do I have?"_ -- _"Show me my orgs"_ +- `"What organizations do I have?"` +- `"Show me my orgs"` ### list_projects List all projects in your Trigger.dev account. **Example usage:** -- _"What projects do I have?"_ -- _"List my Trigger.dev projects"_ +- `"What projects do I have?"` +- `"List my Trigger.dev projects"` ### create_project_in_org Create a new project in an organization. **Example usage:** -- _"Create a new project called 'my-app'"_ -- _"Set up a new Trigger.dev project"_ +- `"Create a new project called 'my-app'"` +- `"Set up a new Trigger.dev project"` ### initialize_project Initialize Trigger.dev in your project with automatic setup and configuration. **Example usage:** -- _"Set up Trigger.dev in this project"_ -- _"Add Trigger.dev to my app"_ +- `"Set up Trigger.dev in this project"` +- `"Add Trigger.dev to my app"` ## Task Management Tools @@ -56,17 +56,17 @@ Initialize Trigger.dev in your project with automatic setup and configuration. Get the current worker for a project, including the worker version, SDK version, and registered tasks with their payload schemas. **Example usage:** -- _"What tasks are available?"_ -- _"Show me the tasks in dev"_ +- `"What tasks are available?"` +- `"Show me the tasks in dev"` ### trigger_task Trigger a task to run with a specific payload. You can add a delay, set tags, configure retries, choose a machine size, set a TTL, or use an idempotency key. **Example usage:** -- _"Run the email-notification task"_ -- _"Trigger my-task with userId 123"_ -- _"Execute the sync task in production"_ +- `"Run the email-notification task"` +- `"Trigger my-task with userId 123"` +- `"Execute the sync task in production"` ## Run Monitoring Tools @@ -75,32 +75,32 @@ Trigger a task to run with a specific payload. You can add a delay, set tags, co Get detailed information about a specific task run, including logs and status. Enable debug mode to get the full trace with all logs and spans. **Example usage:** -- _"Show me details for run run_abc123"_ -- _"Why did this run fail?"_ +- `"Show me details for run run_abc123"` +- `"Why did this run fail?"` ### list_runs List runs for a project. Filter by status, task, tags, version, machine size, or time period. **Example usage:** -- _"Show me recent runs"_ -- _"List failed runs from the last 7 days"_ -- _"What runs are currently executing?"_ +- `"Show me recent runs"` +- `"List failed runs from the last 7 days"` +- `"What runs are currently executing?"` ### wait_for_run_to_complete Wait for a specific run to finish and return the result. **Example usage:** -- _"Wait for run run_abc123 to complete"_ +- `"Wait for run run_abc123 to complete"` ### cancel_run Cancel a running or queued run. **Example usage:** -- _"Cancel run run_abc123"_ -- _"Stop that task"_ +- `"Cancel run run_abc123"` +- `"Stop that task"` ## Deployment Tools @@ -109,24 +109,24 @@ Cancel a running or queued run. Deploy your project to staging or production. **Example usage:** -- _"Deploy to production"_ -- _"Deploy to staging"_ +- `"Deploy to production"` +- `"Deploy to staging"` ### list_deploys List deployments for a project. Filter by status or time period. **Example usage:** -- _"Show me recent deployments"_ -- _"What's deployed to production?"_ +- `"Show me recent deployments"` +- `"What's deployed to production?"` ### list_preview_branches List all preview branches in the project. **Example usage:** -- _"What preview branches exist?"_ -- _"Show me preview deployments"_ +- `"What preview branches exist?"` +- `"Show me preview deployments"` The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. diff --git a/docs/skills.mdx b/docs/skills.mdx index eb4add4795..f12c5c36eb 100644 --- a/docs/skills.mdx +++ b/docs/skills.mdx @@ -7,7 +7,11 @@ tag: "new" ## What are agent skills? -Skills are portable instruction sets that teach AI coding assistants how to use Trigger.dev effectively. Unlike vendor-specific config files (`.cursor/rules`, `CLAUDE.md`), skills use an open standard that works across all major AI assistants. For example, Cursor users and Claude Code users can get the same knowledge from a single install. +Skills are portable instruction sets that teach AI coding assistants how to use Trigger.dev effectively. Unlike vendor-specific config files (`.cursor/rules`, `CLAUDE.md`), skills use an open standard that works across all major AI assistants. For example, Cursor users and Claude Code users can get the same knowledge from a single install. + + + Skills are one of three AI tools we provide. You can also install [Agent Rules](/mcp-agent-rules) for client-specific rule sets or the [MCP Server](/mcp-introduction) for live project interaction. See the [comparison table](/building-with-ai#skills-vs-agent-rules-vs-mcp) for details. + Skills are installed as directories containing a `SKILL.md` file. Each `SKILL.md` includes YAML frontmatter (name, description) and markdown instructions with patterns, examples, and best practices that AI assistants automatically discover and follow. @@ -68,15 +72,15 @@ Skills work with any AI coding assistant that supports the [Agent Skills standar ## Next steps + + Install comprehensive rule sets directly into your AI client. + Give your AI assistant direct access to Trigger.dev tools and APIs. Learn the task patterns that skills teach your AI assistant. - - Build durable AI workflows with prompt chaining and human-in-the-loop. - Browse the full Agent Skills ecosystem.