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

package/docs/queue-concurrency.mdx

@@ -0,0 +1,354 @@
+---
+title: "Concurrency & Queues"
+description: "Configure what you want to happen when there is more than one run at a time."
+---
+
+When you trigger a task, it isn't executed immediately. Instead, the task [run](/runs) is placed into a queue for execution.
+
+By default, each task gets its own queue and the concurrency is only limited by your environment concurrency limit. If you need more control (for example, to limit concurrency or share limits across multiple tasks), you can define a custom queue as described later.
+
+Controlling concurrency is useful when you have a task that can't be run concurrently, or when you want to limit the number of runs to avoid overloading a resource.
+
+It's important to note that only actively executing runs count towards concurrency limits. Runs that are delayed or waiting in a queue do not consume concurrency slots until they begin execution.
+
+## Default concurrency
+
+By default, all tasks have an unbounded concurrency limit, limited only by the overall concurrency limits of your environment.
+
+<Note>
+  Your environment has a base concurrency limit and a burstable limit (default burst factor of 2.0x
+  the base limit). Individual queues are limited by the base concurrency limit, not the burstable
+  limit. For example, if your base limit is 10, your environment can burst up to 20 concurrent runs,
+  but any single queue can have at most 10 concurrent runs. If you're a paying customer you can
+  request higher burst limits by [contacting us](https://www.trigger.dev/contact).
+</Note>
+
+## Setting task concurrency
+
+You can set the concurrency limit for a task by setting the `concurrencyLimit` property on the task's queue. This limits the number of runs that can be executing at any one time:
+
+```ts /trigger/one-at-a-time.ts
+// This task will only run one at a time
+export const oneAtATime = task({
+  id: "one-at-a-time",
+  queue: {
+    concurrencyLimit: 1,
+  },
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+This is useful if you need to control access to a shared resource, like a database or an API that has rate limits.
+
+## Sharing concurrency between tasks
+
+As well as putting queue settings directly on a task, you can define a queue and reuse it across multiple tasks. This allows you to share the same concurrency limit:
+
+```ts /trigger/queue.ts
+export const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 1,
+});
+
+export const task1 = task({
+  id: "task-1",
+  queue: myQueue,
+  run: async (payload: { message: string }) => {
+    // ...
+  },
+});
+
+export const task2 = task({
+  id: "task-2",
+  queue: myQueue,
+  run: async (payload: { message: string }) => {
+    // ...
+  },
+});
+```
+
+In this example, `task1` and `task2` share the same queue, so only one of them can run at a time.
+
+## Setting the queue when you trigger a run
+
+When you trigger a task you can override the default queue. This is really useful if you sometimes have high priority runs.
+
+The task and queue definition:
+
+```ts /trigger/override-concurrency.ts
+const paidQueue = queue({
+  name: "paid-users",
+  concurrencyLimit: 10,
+});
+
+export const generatePullRequest = task({
+  id: "generate-pull-request",
+  queue: {
+    //normally when triggering this task it will be limited to 1 run at a time
+    concurrencyLimit: 1,
+  },
+  run: async (payload) => {
+    //todo generate a PR using OpenAI
+  },
+});
+```
+
+Triggering from your backend and overriding the queue:
+
+```ts app/api/push/route.ts
+import { generatePullRequest } from "~/trigger/override-concurrency";
+
+export async function POST(request: Request) {
+  const data = await request.json();
+
+  if (data.branch === "main") {
+    //trigger the task, with the paid users queue
+    const handle = await generatePullRequest.trigger(data, {
+      // Set the paid users queue
+      queue: "paid-users",
+    });
+
+    return Response.json(handle);
+  } else {
+    //triggered with the default queue (concurrency of 1)
+    const handle = await generatePullRequest.trigger(data);
+    return Response.json(handle);
+  }
+}
+```
+
+## Concurrency keys and per-tenant queuing
+
+If you're building an application where you want to run tasks for your users, you might want a separate queue for each of your users (or orgs, projects, etc.).
+
+You can do this by using `concurrencyKey`. It creates a copy of the queue for each unique value of the key.
+
+Your backend code:
+
+```ts app/api/pr/route.ts
+import { generatePullRequest } from "~/trigger/override-concurrency";
+
+export async function POST(request: Request) {
+  const data = await request.json();
+
+  if (data.isFreeUser) {
+    //the "free-users" queue has a concurrency limit of 1
+    const handle = await generatePullRequest.trigger(data, {
+      queue: "free-users",
+      //this creates a free-users queue for each user
+      concurrencyKey: data.userId,
+    });
+
+    //return a success response with the handle
+    return Response.json(handle);
+  } else {
+    //the "paid-users" queue has a concurrency limit of 10
+    const handle = await generatePullRequest.trigger(data, {
+      queue: "paid-users",
+      //this creates a paid-users queue for each user
+      concurrencyKey: data.userId,
+    });
+
+    //return a success response with the handle
+    return Response.json(handle);
+  }
+}
+```
+
+## Concurrency and subtasks
+
+When you trigger a task that has subtasks, the subtasks will not inherit the queue from the parent task. Unless otherwise specified, subtasks will run on their own queue
+
+```ts /trigger/subtasks.ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    //trigger a subtask
+    await subtask.triggerAndWait(payload);
+  },
+});
+
+// This subtask will run on its own queue
+export const subtask = task({
+  id: "subtask",
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+## Waits and concurrency
+
+With our [task checkpoint system](/how-it-works#the-checkpoint-resume-system), tasks can wait at various waitpoints (like waiting for subtasks to complete, delays, or external events). The way this system interacts with the concurrency system is important to understand.
+
+Concurrency is only released when a run reaches a waitpoint and is checkpointed. When a run is checkpointed, it transitions to the `WAITING` state and releases its concurrency slot back to both the queue and the environment, allowing other runs to execute or resume.
+
+This means that:
+
+- Only actively executing runs count towards concurrency limits
+- Runs in the `WAITING` state (checkpointed at waitpoints) do not consume concurrency slots
+- You can have more runs in the `WAITING` state than your queue's concurrency limit
+- When a waiting run resumes (e.g., when a subtask completes), it must re-acquire a concurrency slot
+
+For example, if you have a queue with a `concurrencyLimit` of 1:
+
+- You can only have exactly 1 run executing at a time
+- You may have multiple runs in the `WAITING` state that belong to that queue
+- When the executing run reaches a waitpoint and checkpoints, it releases its slot
+- The next queued run can then begin execution
+
+### Waiting for a subtask on a different queue
+
+When a parent task triggers and waits for a subtask on a different queue, the parent task will checkpoint and release its concurrency slot once it reaches the wait point. This prevents environment deadlocks where all concurrency slots would be occupied by waiting tasks.
+
+```ts /trigger/waiting.ts
+export const parentTask = task({
+  id: "parent-task",
+  queue: {
+    concurrencyLimit: 1,
+  },
+  run: async (payload) => {
+    //trigger a subtask and wait for it to complete
+    await subtask.triggerAndWait(payload);
+    // The parent task checkpoints here and releases its concurrency slot
+    // allowing other tasks to execute while waiting
+  },
+});
+
+export const subtask = task({
+  id: "subtask",
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+When the parent task reaches the `triggerAndWait` call, it checkpoints and transitions to the `WAITING` state, releasing its concurrency slot back to both its queue and the environment. Once the subtask completes, the parent task will resume and re-acquire a concurrency slot.
+
+## Managing queues with the SDK
+
+The SDK provides a `queues` namespace that allows you to manage queues programmatically. You can list, retrieve, pause, resume, and modify concurrency limits for queues.
+
+<Note>
+  Import from `@trigger.dev/sdk`:
+  ```ts
+  import { queues } from "@trigger.dev/sdk";
+  ```
+</Note>
+
+### Listing queues
+
+You can list all queues in your environment with pagination support:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// List all queues (returns paginated results)
+const allQueues = await queues.list();
+
+// With pagination options
+const pagedQueues = await queues.list({
+  page: 1,
+  perPage: 20,
+});
+```
+
+### Retrieving a queue
+
+You can retrieve a specific queue by its ID, or by its type and name:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Using queue ID (starts with "queue_")
+const queueById = await queues.retrieve("queue_1234");
+
+// Using type and name for a task's default queue
+const taskQueue = await queues.retrieve({
+  type: "task",
+  name: "my-task-id",
+});
+
+// Using type and name for a custom queue
+const customQueue = await queues.retrieve({
+  type: "custom",
+  name: "my-custom-queue",
+});
+```
+
+The queue object contains useful information about the queue state:
+
+```ts
+{
+  id: "queue_1234",       // Queue ID
+  name: "my-task-id",     // Queue name
+  type: "task",           // "task" or "custom"
+  running: 5,             // Currently executing runs
+  queued: 10,             // Runs waiting to execute
+  paused: false,          // Whether the queue is paused
+  concurrencyLimit: 10,   // Current concurrency limit
+  concurrency: {
+    current: 10,          // Effective limit
+    base: 10,             // Default limit from code
+    override: null,       // Override value (if set)
+    overriddenAt: null,   // When override was applied
+    overriddenBy: null,   // Who applied the override
+  }
+}
+```
+
+### Pausing and resuming queues
+
+You can pause a queue to prevent new runs from starting. Runs that are currently executing will continue to completion.
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Pause a queue using its ID
+await queues.pause("queue_1234");
+
+// Or using type and name
+await queues.pause({ type: "task", name: "my-task-id" });
+await queues.pause({ type: "custom", name: "my-custom-queue" });
+```
+
+To resume a paused queue and allow new runs to start:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Resume a queue using its ID
+await queues.resume("queue_1234");
+
+// Or using type and name
+await queues.resume({ type: "task", name: "my-task-id" });
+await queues.resume({ type: "custom", name: "my-custom-queue" });
+```
+
+### Overriding concurrency limits
+
+You can temporarily override a queue's concurrency limit. This is useful for scaling up or down based on demand:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Set concurrency limit to 5
+await queues.overrideConcurrencyLimit("queue_1234", 5);
+
+// Or using type and name
+await queues.overrideConcurrencyLimit({ type: "task", name: "my-task-id" }, 20);
+```
+
+To reset the concurrency limit back to the base value defined in your code:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Reset concurrency limit to the base value
+await queues.resetConcurrencyLimit("queue_1234");
+
+// Or using type and name
+await queues.resetConcurrencyLimit({ type: "task", name: "my-task-id" });
+```

package/docs/quick-start.mdx

@@ -0,0 +1,97 @@
+---
+title: "Quick start: add Trigger.dev to your project"
+sidebarTitle: "Quick start"
+description: "Set up Trigger.dev in your existing project in under 3 minutes. Install the SDK, create your first background task, and trigger it from your code."
+---
+
+import CliInitStep from "/snippets/step-cli-init.mdx";
+import CliDevStep from "/snippets/step-cli-dev.mdx";
+import CliRunTestStep from "/snippets/step-run-test.mdx";
+import CliViewRunStep from "/snippets/step-view-run.mdx";
+
+## Set up with AI
+
+Using an AI coding assistant? Copy this prompt and paste it into Claude Code, Cursor, Copilot, Windsurf, or any AI tool. It'll handle the setup for you.
+
+<Accordion title="Copy the setup prompt">
+
+```text
+Help me add Trigger.dev to this project.
+
+## What to do
+
+1. I need a Trigger.dev account. If I don't have one, point me to https://cloud.trigger.dev to sign up. Wait for me to confirm.
+2. Run `npx trigger.dev@latest init` in the project root.
+   - When it asks about the MCP server, recommend I install it (best DX: gives you direct access to Trigger.dev docs, deploys, and run monitoring).
+   - Install the "Hello World" example task when prompted.
+3. Run `npx trigger.dev@latest dev` to start the dev server.
+4. Once the dev server is running, test the example task from the Trigger.dev dashboard.
+5. Set TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js). I can find it on the API Keys page in the dashboard.
+6. Ask me what framework I'm using and show me how to trigger the task from my backend code.
+
+If I've already run init and want the MCP server, run: npx trigger.dev@latest install-mcp
+
+## Critical rules
+
+- ALWAYS import from `@trigger.dev/sdk`. NEVER import from `@trigger.dev/sdk/v3`.
+- NEVER use `client.defineJob()` — that's the deprecated v2 API.
+- Use type-only imports when triggering from backend code to avoid bundling task code:
+
+  import type { myTask } from "./trigger/example";
+  import { tasks } from "@trigger.dev/sdk";
+
+  const handle = await tasks.trigger<typeof myTask>("hello-world", { message: "Hello from my app!" });
+
+## When done, point me to
+
+- Writing tasks: https://trigger.dev/docs/tasks/overview
+- Real-time updates: https://trigger.dev/docs/realtime/overview
+- AI tooling: https://trigger.dev/docs/building-with-ai
+```
+
+</Accordion>
+
+## Manual setup
+
+<Steps titleSize="h3">
+
+<Step title="Create a Trigger.dev account">
+
+Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/open-source-self-hosting)). The onboarding flow will guide you through creating your first organization and project.
+
+</Step>
+
+<CliInitStep />
+<CliDevStep />
+<CliRunTestStep />
+<CliViewRunStep />
+
+</Steps>
+
+## Triggering tasks from your app
+
+The test page in the dashboard is great for verifying your task works. To trigger tasks from your own code, you'll need to set the `TRIGGER_SECRET_KEY` environment variable. Grab it from the API Keys page in the dashboard and add it to your `.env` file.
+
+```bash .env
+TRIGGER_SECRET_KEY=tr_dev_...
+```
+
+See [Triggering](/triggering) for the full guide, or jump straight to framework-specific setup for [Next.js](/guides/frameworks/nextjs), [Remix](/guides/frameworks/remix), or [Node.js](/guides/frameworks/nodejs).
+
+## Next steps
+
+<CardGroup cols={2}>
+<Card title="Building with AI" icon="brain" href="/building-with-ai">
+  Build Trigger.dev projects using AI coding assistants
+</Card>
+  <Card title="How to trigger your tasks" icon="bolt" href="/triggering">
+    Trigger tasks from your backend code
+  </Card>
+  <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview">
+    Task options, lifecycle hooks, retries, and queues
+  </Card>
+  <Card title="Guides and example projects" icon="books" href="/guides/introduction">
+  Framework guides and working example repos
+</Card>
+
+</CardGroup>

package/docs/realtime/auth.mdx

@@ -0,0 +1,208 @@
+---
+title: Realtime authentication
+sidebarTitle: Realtime auth
+description: Authenticating real-time API requests with Public Access Tokens or Trigger Tokens
+---
+
+To use the Realtime API, you need to authenticate your requests with Public Access Tokens or Trigger Tokens. These tokens provide secure, scoped access to your runs and can be used in both frontend and backend applications.
+
+## Token Types
+
+There are two types of tokens you can use with the Realtime API:
+
+- **[Public Access Tokens](#public-access-tokens-for-subscribing-to-runs)** - Used to read and subscribe to run data. Can be used in both the frontend and backend.
+- **[Trigger Tokens](#trigger-tokens-for-frontend-triggering-only)** - Used to trigger tasks from your frontend. These are more secure, single-use tokens that can only be used in the frontend.
+
+## Public Access Tokens (for subscribing to runs)
+
+Use Public Access Tokens to subscribe to runs and receive real-time updates in your frontend or backend.
+
+### Creating Public Access Tokens
+
+You can create a Public Access Token using the `auth.createPublicToken` function in your **backend** code:
+
+```tsx
+// Somewhere in your backend code
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken(); // 👈 this public access token has no permissions, so is pretty useless!
+```
+
+### Scopes
+
+By default a Public Access Token has no permissions. You must specify the scopes you need when creating a Public Access Token:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: true, // ❌ this token can read all runs, possibly useful for debugging/testing
+    },
+  },
+});
+```
+
+This will allow the token to read all runs, which is probably not what you want. You can specify only certain runs by passing an array of run IDs:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_1234", "run_5678"], // ✅ this token can read only these runs
+    },
+  },
+});
+```
+
+You can scope the token to only read certain tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"], // 👈 this token can read all runs of these tasks
+    },
+  },
+});
+```
+
+Or tags:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tags: ["my-tag-1", "my-tag-2"], // 👈 this token can read all runs with these tags
+    },
+  },
+});
+```
+
+Or a specific batch of runs:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      batch: "batch_1234", // 👈 this token can read all runs in this batch
+    },
+  },
+});
+```
+
+You can also combine scopes. For example, to read runs with specific tags and for specific tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"],
+      tags: ["my-tag-1", "my-tag-2"],
+    },
+  },
+});
+```
+
+### Expiration
+
+By default, Public Access Token's expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  expirationTime: "1hr",
+});
+```
+
+- If `expirationTime` is a string, it will be treated as a time span
+- If `expirationTime` is a number, it will be treated as a Unix timestamp
+- If `expirationTime` is a `Date`, it will be treated as a date
+
+The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
+
+### Auto-generated tokens
+
+When you [trigger tasks](/triggering) from your backend, the `handle` received includes a `publicAccessToken` field. This token can be used to authenticate real-time requests in your frontend application.
+
+By default, auto-generated tokens expire after 15 minutes and have a read scope for the specific run(s) that were triggered. You can customize the expiration by passing a `publicTokenOptions` object to the trigger function.
+
+See our [triggering documentation](/triggering) for detailed examples of how to trigger tasks and get auto-generated tokens.
+
+<Note>
+**Where should I create tokens?** The standard pattern is to create tokens in your backend code (API route, server action) after triggering a task, then pass the token to your frontend. The `handle.publicAccessToken` returned by `tasks.trigger()` already does this for you. You rarely need to create tokens inside a task itself.
+</Note>
+
+### Subscribing to runs with Public Access Tokens
+
+Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API in both backend and frontend applications.
+
+**Backend usage:** See our [backend documentation](/realtime/backend) for examples of what you can do with Realtime in your backend once you have authenticated with a token.
+
+**Frontend usage:** See our [React hooks documentation](/realtime/react-hooks) for examples of using tokens with frontend components.
+
+## Trigger Tokens (for frontend triggering only)
+
+For triggering tasks from your frontend, you need special "trigger" tokens. These tokens can only be used once to trigger a task and are more secure than regular Public Access Tokens.
+
+### Creating Trigger Tokens
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task");
+```
+
+### Multiple tasks
+
+You can pass multiple tasks to create a token that can trigger multiple tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken(["my-task-1", "my-task-2"]);
+```
+
+### Multiple use
+
+You can also create tokens that can be used multiple times:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  multipleUse: true, // ❌ Use this with caution!
+});
+```
+
+### Expiration
+
+These tokens also expire, with the default expiration time being 15 minutes. You can specify a custom expiration time:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "24hr",
+});
+```
+
+### Triggering tasks from the frontend with Trigger Tokens
+
+Check out our [React hooks documentation](/realtime/react-hooks) for examples of how to use Trigger Tokens in your frontend applications.