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

package/docs/manual-setup.mdx

@@ -0,0 +1,632 @@
+---
+title: "Manual setup"
+description: "How to manually setup Trigger.dev in your project."
+---
+
+This guide covers how to manually set up Trigger.dev in your project, including configuration for different package managers, monorepos, and build extensions. This guide replicates all the steps performed by the `trigger.dev init` command. Follow our [Quickstart](/quick-start) for a more streamlined setup.
+
+## Prerequisites
+
+- Node.js 18.20+ (or Bun runtime)
+- A Trigger.dev account (sign up at [trigger.dev](https://trigger.dev))
+- TypeScript 5.0.4 or later (for TypeScript projects)
+
+## CLI Authentication
+
+Before setting up your project, you need to authenticate the CLI with Trigger.dev:
+
+```bash
+# Login to Trigger.dev
+npx trigger.dev@latest login
+
+# Or with a specific API URL (for self-hosted instances)
+npx trigger.dev@latest login --api-url https://your-trigger-instance.com
+```
+
+This will open your browser to authenticate. Once authenticated, you'll need to select or create a project in the Trigger.dev dashboard to get your project reference (e.g., `proj_abc123`).
+
+## Package installation
+
+Install the required packages based on your package manager:
+
+<CodeGroup>
+
+```bash npm
+npm add @trigger.dev/sdk@latest
+npm add --save-dev @trigger.dev/build@latest
+```
+
+```bash pnpm
+pnpm add @trigger.dev/sdk@latest
+pnpm add -D @trigger.dev/build@latest
+```
+
+```bash yarn
+yarn add @trigger.dev/sdk@latest
+yarn add -D @trigger.dev/build@latest
+```
+
+```bash bun
+bun add @trigger.dev/sdk@latest
+bun add -D @trigger.dev/build@latest
+```
+
+</CodeGroup>
+
+## Environment variables
+
+For local development, you need to set up the `TRIGGER_SECRET_KEY` environment variable. This key authenticates your application with Trigger.dev.
+
+1. Go to your project dashboard in Trigger.dev
+2. Navigate to the "API Keys" page
+3. Copy the **DEV** secret key
+4. Add it to your local environment file:
+
+```bash
+TRIGGER_SECRET_KEY=tr_dev_xxxxxxxxxx
+```
+
+### Self-hosted instances
+
+If you're using a self-hosted Trigger.dev instance, also set:
+
+```bash
+TRIGGER_API_URL=https://your-trigger-instance.com
+```
+
+## CLI setup
+
+You can run the Trigger.dev CLI in two ways:
+
+### Option 1: Using npx/pnpm dlx/yarn dlx
+
+```bash
+# npm
+npx trigger.dev@latest dev
+
+# pnpm
+pnpm dlx trigger.dev@latest dev
+
+# yarn
+yarn dlx trigger.dev@latest dev
+```
+
+### Option 2: Add as dev dependency
+
+Add the CLI to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "trigger.dev": "^4.0.0"
+  }
+}
+```
+
+Then add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev:trigger": "trigger dev",
+    "deploy:trigger": "trigger deploy"
+  }
+}
+```
+
+### Version pinning
+
+Make sure to pin the version of the CLI to the same version as the SDK that you are using:
+
+```json
+"devDependencies": {
+  "trigger.dev": "^4.0.0",
+  "@trigger.dev/build": "^4.0.0"
+},
+"dependencies": {
+  "@trigger.dev/sdk": "^4.0.0"
+}
+```
+
+While running the CLI `dev` or `deploy` commands, the CLI will automatically detect mismatched versions and warn you.
+
+## Configuration file
+
+Create a `trigger.config.ts` file in your project root (or `trigger.config.mjs` for JavaScript projects):
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  // Your project ref from the Trigger.dev dashboard
+  project: "<your-project-ref>", // e.g., "proj_abc123"
+
+  // Directories containing your tasks
+  dirs: ["./src/trigger"], // Customize based on your project structure
+
+  // Retry configuration
+  retries: {
+    enabledInDev: false, // Enable retries in development
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+
+  // Build configuration (optional)
+  build: {
+    extensions: [], // Build extensions go here
+  },
+
+  // Max duration of a task in seconds
+  maxDuration: 3600,
+});
+```
+
+### Using the Bun runtime
+
+By default, Trigger.dev will use the Node.js runtime. If you're using Bun, you can specify the runtime:
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<your-project-ref>",
+  runtime: "bun",
+  dirs: ["./src/trigger"],
+});
+```
+
+See our [Bun runtime documentation](/guides/frameworks/bun) for more information.
+
+## Add your first task
+
+Create a `trigger` directory (matching the `dirs` in your config) and add an example task:
+
+```typescript src/trigger/example.ts
+import { task } from "@trigger.dev/sdk";
+
+export const helloWorld = task({
+  id: "hello-world",
+  run: async (payload: { name: string }) => {
+    console.log(`Hello ${payload.name}!`);
+
+    return {
+      message: `Hello ${payload.name}!`,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+```
+
+See our [Tasks](/tasks/overview) docs for more information on how to create tasks.
+
+## TypeScript config
+
+If you're using TypeScript, add `trigger.config.ts` to your `tsconfig.json` include array:
+
+```json
+{
+  "compilerOptions": {
+    // ... your existing options
+  },
+  "include": [
+    // ... your existing includes
+    "trigger.config.ts"
+  ]
+}
+```
+
+## Git config
+
+Add `.trigger` to your `.gitignore` file to exclude Trigger.dev's local development files:
+
+```bash
+# Trigger.dev
+.trigger
+```
+
+If you don't have a `.gitignore` file, create one with this content.
+
+## React hooks setup
+
+If you're building a React frontend application and want to display task status in real-time, install the React hooks package:
+
+### Installation
+
+```bash
+# npm
+npm install @trigger.dev/react-hooks@latest
+
+# pnpm
+pnpm add @trigger.dev/react-hooks@latest
+
+# yarn
+yarn add @trigger.dev/react-hooks@latest
+
+# bun
+bun add @trigger.dev/react-hooks@latest
+```
+
+### Basic usage
+
+1. **Generate a Public Access Token** in your backend:
+
+```typescript
+import { auth } from "@trigger.dev/sdk";
+
+// In your backend API
+export async function getPublicAccessToken() {
+  const publicAccessToken = await auth.createPublicToken({
+    scopes: ["read:runs"], // Customize based on needs
+  });
+
+  return publicAccessToken;
+}
+```
+
+2. **Use hooks to monitor tasks**:
+
+```tsx
+import { useRealtimeRun } from "@trigger.dev/react-hooks";
+
+export function TaskStatus({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, error } = useRealtimeRun(runId, {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!run) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>Status: {run.status}</p>
+      <p>Progress: {run.completedAt ? "Complete" : "Running..."}</p>
+    </div>
+  );
+}
+```
+
+For more information, see the [React Hooks documentation](/realtime/react-hooks/overview).
+
+## Build extensions
+
+Build extensions allow you to customize the build process. Ensure you have the `@trigger.dev/build` package installed in your project (see [package installation](#package-installation)).
+
+Now you can use any of the built-in extensions:
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
+
+export default defineConfig({
+  project: "<project-ref>",
+  build: {
+    extensions: [
+      prismaExtension({
+        mode: "legacy",
+        schema: "prisma/schema.prisma",
+        migrate: true, // Run migrations on deploy
+      }),
+    ],
+  },
+});
+```
+
+See our [Build extensions](/config/extensions/overview) docs for more information on how to use build extensions and the available extensions.
+
+## Monorepo setup
+
+There are two main approaches for setting up Trigger.dev in a monorepo:
+
+1. **Tasks as a package**: Create a separate package for your Trigger.dev tasks that can be shared across apps
+2. **Tasks in apps**: Install Trigger.dev directly in individual apps that need background tasks
+
+Both approaches work well depending on your needs. Use the tasks package approach if you want to share tasks across multiple applications, or the app-based approach if tasks are specific to individual apps.
+
+### Approach 1: Tasks as a package (Turborepo)
+
+This approach creates a dedicated tasks package that can be consumed by multiple apps in your monorepo.
+
+#### 1. Set up workspace configuration
+
+**Root `package.json`**:
+
+```json
+{
+  "name": "my-monorepo",
+  "private": true,
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "lint": "turbo run lint"
+  },
+  "devDependencies": {
+    "turbo": "^2.4.4",
+    "typescript": "5.8.2"
+  },
+  "packageManager": "pnpm@9.0.0"
+}
+```
+
+**`pnpm-workspace.yaml`**:
+
+```yaml
+packages:
+  - "apps/*"
+  - "packages/*"
+```
+
+**`turbo.json`**:
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "ui": "tui",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [".next/**", "!.next/cache/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {
+      "dependsOn": ["^lint"]
+    }
+  }
+}
+```
+
+#### 2. Create the tasks package
+
+**`packages/tasks/package.json`**:
+
+```json
+{
+  "name": "@repo/tasks",
+  "version": "0.0.0",
+  "dependencies": {
+    "@trigger.dev/sdk": "^4.0.0"
+  },
+  "devDependencies": {
+    "@trigger.dev/build": "^4.0.0"
+  },
+  "exports": {
+    ".": "./src/trigger/index.ts",
+    "./trigger": "./src/index.ts"
+  }
+}
+```
+
+**`packages/tasks/trigger.config.ts`**:
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<your-project-ref>", // Replace with your project reference
+  dirs: ["./src/trigger"],
+  retries: {
+    enabledInDev: true,
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+  maxDuration: 3600,
+});
+```
+
+**`packages/tasks/src/index.ts`**:
+
+```typescript
+export * from "@trigger.dev/sdk"; // Export values and types from the Trigger.dev sdk
+```
+
+**`packages/tasks/src/trigger/index.ts`**:
+
+```typescript
+// Export tasks
+export * from "./example";
+```
+
+**`packages/tasks/src/trigger/example.ts`**:
+
+```typescript
+import { task } from "@trigger.dev/sdk";
+
+export const helloWorld = task({
+  id: "hello-world",
+  run: async (payload: { name: string }) => {
+    console.log(`Hello ${payload.name}!`);
+
+    return {
+      message: `Hello ${payload.name}!`,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+```
+
+See our [turborepo-prisma-tasks-package example](https://github.com/triggerdotdev/examples/tree/main/monorepos/turborepo-prisma-tasks-package) for a more complete example.
+
+#### 3. Use tasks in your apps
+
+**`apps/web/package.json`**:
+
+```json
+{
+  "name": "web",
+  "dependencies": {
+    "@repo/tasks": "workspace:*",
+    "next": "^15.2.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}
+```
+
+**`apps/web/app/api/actions.ts`**:
+
+```typescript
+"use server";
+
+import { tasks } from "@repo/tasks/trigger";
+import type { helloWorld } from "@repo/tasks";
+//     👆 type only import
+
+export async function triggerHelloWorld(name: string) {
+  try {
+    const handle = await tasks.trigger<typeof helloWorld>("hello-world", {
+      name: name,
+    });
+
+    return handle.id;
+  } catch (error) {
+    console.error(error);
+    return { error: "something went wrong" };
+  }
+}
+```
+
+#### 4. Development workflow
+
+Run the development server for the tasks package:
+
+```bash
+# From the root of your monorepo
+cd packages/tasks
+npx trigger.dev@latest dev
+
+# Or using turbo (if you add dev:trigger script to tasks package.json)
+turbo run dev:trigger --filter=@repo/tasks
+```
+
+### Approach 2: Tasks in apps (Turborepo)
+
+This approach installs Trigger.dev directly in individual apps that need background tasks.
+
+#### 1. Install in your app
+
+**`apps/web/package.json`**:
+
+```json
+{
+  "name": "web",
+  "dependencies": {
+    "@trigger.dev/sdk": "^4.0.0",
+    "next": "^15.2.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@trigger.dev/build": "^4.0.0"
+  }
+}
+```
+
+#### 2. Add configuration
+
+**`apps/web/trigger.config.ts`**:
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<your-project-ref>", // Replace with your project reference
+  dirs: ["./src/trigger"],
+  retries: {
+    enabledInDev: true,
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+  maxDuration: 3600,
+});
+```
+
+#### 3. Create tasks
+
+**`apps/web/src/trigger/example.ts`**:
+
+```typescript
+import { task } from "@trigger.dev/sdk";
+
+export const helloWorld = task({
+  id: "hello-world",
+  run: async (payload: { name: string }) => {
+    console.log(`Hello ${payload.name}!`);
+
+    return {
+      message: `Hello ${payload.name}!`,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+```
+
+#### 4. Use tasks in your app
+
+**`apps/web/app/api/actions.ts`**:
+
+```typescript
+"use server";
+
+import { tasks } from "@trigger.dev/sdk";
+import type { helloWorld } from "../../src/trigger/example";
+//     👆 type only import
+
+export async function triggerHelloWorld(name: string) {
+  try {
+    const handle = await tasks.trigger<typeof helloWorld>("hello-world", {
+      name: name,
+    });
+
+    return handle.id;
+  } catch (error) {
+    console.error(error);
+    return { error: "something went wrong" };
+  }
+}
+```
+
+#### 5. Development workflow
+
+```bash
+# From the app directory
+cd apps/web
+npx trigger.dev@latest dev
+
+# Or from the root using turbo
+turbo run dev:trigger --filter=web
+```
+
+## Example projects
+
+You can find a growing list of example projects in our [examples](/guides/introduction) section.
+
+## Troubleshooting
+
+If you run into any issues, please check our [Troubleshooting](/troubleshooting) page.
+
+## Feedback
+
+If you have any feedback, please let us know by [opening an issue](https://github.com/triggerdotdev/trigger.dev/issues).

package/docs/mcp-agent-rules.mdx

@@ -0,0 +1,41 @@
+---
+title: "Agent rules"
+description: "Trigger.dev agent rules are now agent skills, installed with the trigger.dev CLI."
+sidebarTitle: "Agent rules"
+---
+
+<Note>
+  Agent rules are now **agent skills**. The standalone rule files have been replaced by skills that
+  work across every major AI assistant from a single install. See [Skills](/skills).
+</Note>
+
+## What changed
+
+Trigger.dev used to install per-tool *rule files* (`.cursor/rules/trigger.*.mdc`, regions in `CLAUDE.md`, and so on) fetched from GitHub. That has been replaced by [agent skills](/skills): `SKILL.md` directories in the open [Agent Skills standard](https://agentskills.io) that install with the CLI, draw their API guidance from a version-pinned reference in `@trigger.dev/sdk`, and load on demand instead of always sitting in your context.
+
+The install command is the same, and now installs skills:
+
+```bash
+npx trigger.dev@latest skills
+```
+
+`npx trigger.dev@latest install-rules` still works as an alias, and `trigger dev` offers to install the skills on first run.
+
+The old task and realtime guidance now lives in the `trigger-authoring-tasks` and `trigger-realtime-and-frontend` skills, alongside two new skills for building `chat.agent` AI agents. See [Skills](/skills) for the full list and supported assistants.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/skills">
+    Install Trigger.dev agent skills into your AI coding assistant.
+  </Card>
+  <Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
+    Give your AI assistant direct access to Trigger.dev tools and APIs.
+  </Card>
+  <Card title="Building with AI" icon="layer-group" href="/building-with-ai">
+    See how skills and the MCP server compare.
+  </Card>
+  <Card title="Writing tasks" icon="code" href="/tasks/overview">
+    Learn the task patterns that skills teach your AI assistant.
+  </Card>
+</CardGroup>