Docs – v4 GA updates (#2298)

* Adds new features table to top of v4 upgrade guide * Adds wait idempotency to wait-until, wait-for, and wait-for-token pages * Adds new priority docs page and updates the v4 upgrade guide * Adds new task lifecycle hooks * Removes the message about requiring tasks to be exported * Adds new global lifecycle hooks section * Moves sections from upgrade guide into the table * Adds hidden task page * Improves the global lifecycle hooks section * Updates middleware and locals section * Adds new useWaitToken page to the react hooks section * Adds a new ai.tool section * Moves Docker (legacy) page into self-hosting section * Removes known issues from v4 upgrade guide * Replace “toolTask” with “ai.tool” in the Streams page example * Renames guide to “Migrating from v3” and adds redirect * Remove references to v4 * Removes changelog from migration guide * The installation guide now references `@latest update` * Changes all references from `/sdk/v3` to `/sdk` * Updates @v4-beta to @latest * Fixed broken link * Fixes broken link * Adds an upgrade to v4 using AI section * Fixes 2 broken links * Adds an entry for targetting preview branches * Updates the run statuses * Adds boolean helpers section to the runs and realtime pages * Updates the concurrency page * Updates the test page to include the new options * Adds SDK and curl options for the preview branch targeting * Updates new bulk actions page * Remove the releasing concurrency section * Got rid of some more @v4-beta mentions * Improved rate limit docs * Improved migrating docs * Removed commented sections of the docs * useWaitToken hook * Fixed the description * Fix for missing test image --------- Co-authored-by: Matt Aitken <matt@mattaitken.com> Co-authored-by: Dan <8297864+D-K-P@users.noreply.github.com>
2025-08-18 12:34:55 +01:00
parent 78af477efc
commit fade22015f
127 changed files with 1668 additions and 606 deletions
@@ -39,7 +39,7 @@ The default URL is `https://api.trigger.dev`.
 If you prefer to manually configure the SDK, you can call the `configure` method:

 ```ts
-import { configure } from "@trigger.dev/sdk/v3";
+import { configure } from "@trigger.dev/sdk";
 import { myTask } from "./trigger/myTasks";

 configure({
@@ -3,16 +3,10 @@ title: "Bulk actions"
 description: "Perform actions like replay and cancel on multiple runs at once."
 ---

-Bulk actions allow you to perform operations like replaying or 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.
-
-## Bulk replaying
-
-You can replay multiple runs at once by selecting them from the table on the Runs page using the checkbox on the left hand side of the row. Then click the "Replay runs" button from the bulk action bar that appears at the bottom of the screen.
-
-This is especially useful if you have lots of failed runs and want to run them all again. To do this, first filter the runs by the status you want, then select all the runs you want to replay and click the "Replay runs" button from the bulk action bar at the bottom of the page.
+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-replaying-runs.mp4"
+  src="https://content.trigger.dev/bulk-actions.mp4"
  preload="auto"
  controls={true}
  loop
@@ -22,19 +16,34 @@ This is especially useful if you have lots of failed runs and want to run them a
  height="100%"
 />

-## Bulk canceling
+## How to create a new bulk action

-Similar to replaying multiple runs, you can cancel multiple runs at once. This is particularly useful when you have a batch of runs that you want to stop, perhaps because they were triggered with incorrect parameters or are no longer needed.
+<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Open the bulk action panel from the top right of the runs page

-To cancel multiple runs:
+![Access bulk actions](/images/bulk-action-open-panel.png)

-1. Filter the runs table to show the runs you want to cancel (e.g., all runs with status "QUEUED" or "EXECUTING")
-2. Use the checkboxes on the left side of the runs table to select the runs you want to cancel 
-3. Click the "Cancel runs" button in the bulk action bar that appears at the bottom of the screen

-After confirming, all selected runs that can be canceled (those in appropriate states like QUEUED or EXECUTING) will be canceled. The status of these runs will change to "CANCELED" and they will not be resumed.
+<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 cannot be canceled.
+  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>
@@ -2,10 +2,8 @@
 title: "CLI preview archive command"
 sidebarTitle: "preview archive"
 description: "The `trigger.dev preview archive` command can be used to archive a preview branch."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
 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";
@@ -14,22 +12,20 @@ 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";

-<UpgradeToV4Note />
-
 Run the command like this:

 <CodeGroup>

 ```bash npm
-npx trigger.dev@v4-beta preview archive
+npx trigger.dev@latest preview archive
 ```

 ```bash pnpm
-pnpm dlx trigger.dev@v4-beta preview archive
+pnpm dlx trigger.dev@latest preview archive
 ```

 ```bash yarn
-yarn dlx trigger.dev@v4-beta preview archive
+yarn dlx trigger.dev@latest preview archive
 ```

 </CodeGroup>
@@ -39,7 +35,7 @@ It will archive the preview branch, automatically detecting the branch name from
 ## Arguments

 ```
-npx trigger.dev@v4-beta preview archive [path]
+npx trigger.dev@latest preview archive [path]
 ```

 <ProjectPathArg />
@@ -2,10 +2,8 @@
 title: "CLI switch command"
 sidebarTitle: "switch"
 description: "The `trigger.dev switch` command can be used to switch between profiles."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
 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";
@@ -14,22 +12,20 @@ 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";

-<UpgradeToV4Note />
-
 Run the command like this:

 <CodeGroup>

 ```bash npm
-npx trigger.dev@v4-beta switch [profile]
+npx trigger.dev@latest switch [profile]
 ```

 ```bash pnpm
-pnpm dlx trigger.dev@v4-beta switch [profile]
+pnpm dlx trigger.dev@latest switch [profile]
 ```

 ```bash yarn
-yarn dlx trigger.dev@v4-beta switch [profile]
+yarn dlx trigger.dev@latest switch [profile]
 ```

 </CodeGroup>
@@ -39,7 +35,7 @@ It will switch to the specified profile. If no profile is specified, it will lis
 ## Arguments

 ```
-npx trigger.dev@v4-beta switch [profile]
+npx trigger.dev@latest switch [profile]
 ```

 <ParamField body="Profile" type="[profile]">
@@ -11,7 +11,7 @@ import NodeVersions from "/snippets/node-versions.mdx";
 The `trigger.config.ts` file is used to configure your Trigger.dev project. It is a TypeScript file at the root of your project that exports a default configuration object. Here's an example:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  // Your project ref (you can see it on the Project settings page in the dashboard)
@@ -53,7 +53,7 @@ The config file handles a lot of things, like:
 You can specify the directories where your tasks are located using the `dirs` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -66,7 +66,7 @@ If you omit the `dirs` option, we will automatically detect directories that are
 We will search for TypeScript and JavaScript files in the specified directories and include them in the build process. We automatically exclude files that have `.test` or `.spec` in the name, but you can customize this by specifying glob patterns in the `ignorePatterns` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -80,7 +80,7 @@ export default defineConfig({
 You can add lifecycle functions to get notified when any task starts, succeeds, or fails using `onStart`, `onSuccess` and `onFailure`:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -111,7 +111,7 @@ We use OpenTelemetry (OTEL) for our run logs. This means you get a lot of inform
 Here we add Prisma and OpenAI instrumentations to your `trigger.config.ts` file.

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { PrismaInstrumentation } from "@prisma/instrumentation";
 import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";

@@ -152,7 +152,7 @@ You can also configure custom telemetry exporters to send your traces and logs t
 Then, configure the exporters in your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";

@@ -188,15 +188,10 @@ export default defineConfig({

 Make sure to set the `AXIOM_API_TOKEN` and `AXIOM_DATASET` environment variables in your project.

-<Note>
-  The `logExporters` option is available in the v4 beta SDK. See our [v4 upgrade
-  guide](/upgrade-to-v4) for more information.
-</Note>
-
 It's important to note that you cannot configure exporters using `OTEL_*` environment variables, as they would conflict with our internal telemetry. Instead you should configure the exporters via passing in arguments to the `OTLPTraceExporter` and `OTLPLogExporter` constructors. For example, here is how you can configure exporting to Honeycomb:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";

@@ -235,7 +230,7 @@ export default defineConfig({
 We currently only officially support the `node` runtime, but you can try our experimental `bun` runtime by setting the `runtime` option in your config file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -255,7 +250,7 @@ See our [Bun guide](/guides/frameworks/bun) for more information.
 You can specify the default machine for all tasks in your project:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -271,7 +266,7 @@ See our [machines documentation](/machines) for more information.
 You can set the log level for your project:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -287,7 +282,7 @@ The `logLevel` only determines which logs are sent to the Trigger.dev instance w
 You can set the default `maxDuration` for all tasks in your project:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -303,7 +298,7 @@ See our [maxDuration guide](/runs/max-duration) for more information.
 You can customize the build process using the `build` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -326,7 +321,7 @@ export default defineConfig({
 All code is bundled by default, but you can exclude some packages from the bundle using the `external` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -342,7 +337,7 @@ When a package is excluded from the bundle, it will be added to a dynamically ge
 Each entry in the external should be a package name, not necessarily the import path. For example, if you want to exclude the `ai` package, but you are importing `ai/rsc`, you should just include `ai` in the `external` array:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -363,7 +358,7 @@ export default defineConfig({
 You can customize the `jsx` options that are passed to `esbuild` using the `jsx` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -390,7 +385,7 @@ See the [esbuild JSX documentation](https://esbuild.github.io/content-types/#jsx
 You can add custom [import conditions](https://esbuild.github.io/api/#conditions) to your build using the `conditions` option:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -7,7 +7,7 @@ description: "Use the additionalFiles build extension to copy additional files t
 Import the `additionalFiles` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { additionalFiles } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -7,7 +7,7 @@ description: "Use the additionalPackages build extension to include additional p
 Import the `additionalPackages` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { additionalPackages } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -22,7 +22,7 @@ export default defineConfig({
 This allows you to include additional packages in the build that are not automatically included via imports. This is useful if you want to install a package that includes a CLI tool that you want to invoke in your tasks via `exec`. We will try to automatically resolve the version of the package but you can specify the version by using the `@` symbol:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -7,7 +7,7 @@ description: "Use the aptGet build extension to install system packages into the
 You can install system packages into the deployed image using the `aptGet` extension:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { aptGet } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -22,7 +22,7 @@ export default defineConfig({
 If you want to install a specific version of a package, you can specify the version like this:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -7,7 +7,7 @@ description: "Use the audioWaveform build extension to add support for Audio Wav
 Previously, we installed [Audio Waveform](https://github.com/bbc/audiowaveform) in the build image. That's been moved to a build extension:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";

 export default defineConfig({
@@ -20,7 +20,7 @@ Build extensions allow you to hook into the build system and customize the build
 Build extensions are added to your `trigger.config.ts` file, with a required `name` and optional build hook functions. Here's a simple example of a build extension that just logs a message when the build starts:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -45,7 +45,7 @@ You can also extract that out into a function instead of defining it inline, in
 </Note>

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { BuildExtension } from "@trigger.dev/build";

 export default defineConfig({
@@ -72,7 +72,7 @@ function myExtension(): BuildExtension {
 This allows the extension to add additional dependencies to the list of externals for the build. This is useful for dependencies that are not included in the bundle, but are expected to be available at runtime.

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -94,7 +94,7 @@ export default defineConfig({
 This hook runs before the build starts. It receives the `BuildContext` object as an argument.

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -114,7 +114,7 @@ export default defineConfig({
 If you want to add an esbuild plugin, you must do so in the `onBuildStart` hook. Here's an example of adding a custom esbuild plugin:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -144,7 +144,7 @@ export default defineConfig({
 You can use the `BuildContext.target` property to determine if the build is for `dev` or `deploy`:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -170,7 +170,7 @@ export default defineConfig({
 This hook runs after the build completes. It receives the `BuildContext` object and a `BuildManifest` object as arguments. This is where you can add in one or more `BuildLayer`'s to the context.

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -7,7 +7,7 @@ description: "Use the emitDecoratorMetadata build extension to enable support fo
 If you need support for the `emitDecoratorMetadata` typescript compiler option, import the `emitDecoratorMetadata` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";

 export default defineConfig({
@@ -7,7 +7,7 @@ description: "Use the esbuildPlugin build extension to add existing or custom es
 You can easily add existing or custom esbuild plugins to your build process using the `esbuildPlugin` extension:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { esbuildPlugin } from "@trigger.dev/build/extensions";
 import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";

@@ -7,7 +7,7 @@ description: "Use the ffmpeg build extension to include FFmpeg in your project"
 You can add the `ffmpeg` build extension to your build process:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { ffmpeg } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -26,7 +26,7 @@ By default, this will install the version of `ffmpeg` that is available in the D
 If you need FFmpeg 7.x, you can pass `{ version: "7" }` to the extension. This will install a static build of FFmpeg 7.x instead of using the Debian package:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { ffmpeg } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -11,7 +11,7 @@ You can use pre-built extensions by installing the `@trigger.dev/build` package
 Build extensions are added to your `trigger.config.ts` file under the `build.extensions` property:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "my-project",
@@ -31,7 +31,7 @@ export default defineConfig({
 If you are using a pre-built extension, you can import it from the `@trigger.dev/build` package:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { ffmpeg } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -2,13 +2,8 @@
 title: "Playwright"
 sidebarTitle: "playwright"
 description: "Use the playwright build extension to use Playwright with Trigger.dev"
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
-<UpgradeToV4Note />
-
 If you are using [Playwright](https://playwright.dev/), you should use the Playwright build extension.

 - Automatically installs Playwright and required browser dependencies
@@ -24,7 +19,7 @@ If you are using [Playwright](https://playwright.dev/), you should use the Playw
 You can use it for a simple Playwright setup like this:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { playwright } from "@trigger.dev/build/extensions/playwright";

 export default defineConfig({
@@ -51,7 +46,7 @@ export default defineConfig({
 ### Custom browsers and version

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { playwright } from "@trigger.dev/build/extensions/playwright";

 export default defineConfig({
@@ -72,7 +67,7 @@ export default defineConfig({
 By default, browsers are run in headless mode. If you need to run browsers with a UI (for example, for debugging), set `headless: false`. This will automatically set up a virtual display using Xvfb.

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { playwright } from "@trigger.dev/build/extensions/playwright";

 export default defineConfig({
@@ -16,7 +16,7 @@ If you are using Prisma, you should use the prisma build extension.
 You can use it for a simple Prisma setup like this:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -43,7 +43,7 @@ export default defineConfig({
 If you want to also run migrations during the build process, you can pass in the `migrate` option:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -92,7 +92,7 @@ generator json {
 ```

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -116,7 +116,7 @@ export default defineConfig({
 If you are using [TypedSQL](https://www.prisma.io/typedsql), you'll need to enable it via the `typedSql` option:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -9,7 +9,7 @@ description: "Use the puppeteer build extension to enable support for Puppeteer
 To use Puppeteer in your project, add these build settings to your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";

 export default defineConfig({
@@ -15,7 +15,7 @@ npm add @trigger.dev/python
 Then, you can use the `pythonExtension` build extension in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { pythonExtension } from "@trigger.dev/python/extension";

 export default defineConfig({
@@ -29,7 +29,7 @@ export default defineConfig({
 This will take care of adding python to the build image and setting up the necessary environment variables to execute Python scripts. You can then use our `python` utilities in the `@trigger.dev/python` package to execute Python scripts in your tasks. For example, running a Python script inline in a task:

 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";

 export const myScript = task({
@@ -46,7 +46,7 @@ export const myScript = task({
 You can automatically add python scripts to your project using the `scripts` option in the `pythonExtension` function. This will copy the specified scripts to the build directory during the deploy process. For example:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { pythonExtension } from "@trigger.dev/python/extension";

 export default defineConfig({
@@ -64,7 +64,7 @@ export default defineConfig({
 This will copy all Python files in the `python` directory to the build directory during the deploy process. You can then execute these scripts using the `python.runScript` function:

 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";

 export const myScript = task({
@@ -86,7 +86,7 @@ export const myScript = task({
 If you have a `requirements.txt` file in your project, you can use the `requirementsFile` option in the `pythonExtension` function to install the required packages during the build process. For example:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { pythonExtension } from "@trigger.dev/python/extension";

 export default defineConfig({
@@ -113,7 +113,7 @@ This will install the packages specified in the `requirements.txt` file during t
 If you are using a virtual environment in your project, you can use the `devPythonBinaryPath` option in the `pythonExtension` function to specify the path to the Python binary in the virtual environment. For example:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { pythonExtension } from "@trigger.dev/python/extension";

 export default defineConfig({
@@ -135,7 +135,7 @@ This has no effect in production mode, but in development mode, it will use the
 All of the `python` functions have a streaming version that allows you to stream the output of the Python script as it runs. For example:

 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";

 export const myStreamingScript = task({
@@ -165,7 +165,7 @@ print(os.environ["MY_ENV_VAR"])
 You can also pass additional environment variables to the Python script using the `env` option in the `python.runScript` function. For example:

 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";

 export const myScript = task({
@@ -9,7 +9,7 @@ The `syncEnvVars` build extension will sync env vars from another service into T
 `syncEnvVars` takes an async callback function, and any env vars returned from the callback will be synced to Trigger.dev.

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -37,7 +37,7 @@ The callback is passed a context object with the following properties:
 In this example we're using env vars from [Infisical](https://infisical.com).

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";
 import { InfisicalSDK } from "@infisical/sdk";

@@ -81,7 +81,7 @@ The `syncVercelEnvVars` build extension syncs environment variables from your Ve
 </Note>

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -97,7 +97,7 @@ export default defineConfig({
 Or you can pass in the token and project ID as arguments:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -13,7 +13,7 @@ Context (`ctx`) is a way to get information about a run.
 <RequestExample>

 ```typescript Context example
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 export const parentTask = task({
  id: "parent-task",
@@ -95,7 +95,7 @@ You could use the SDK functions above but it's much easier to use our `syncEnvVa
 In this example we're using env vars from [Infisical](https://infisical.com).

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";
 import { InfisicalSDK } from "@infisical/sdk";

@@ -223,7 +223,7 @@ Usually there will be some useful guidance below this message. If you can't figu
 This happens because `.node` files are native code and can't be bundled like other packages. To fix this, add your package to [`build.external`](/config/config-file#external) in the `trigger.config.ts` file like this:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -1,13 +1,8 @@
 ---
 title: "Preview branches"
 description: "Create isolated environments for each branch of your code, allowing you to test changes before merging to production. You can create preview branches manually or automatically from your git branches."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
-<UpgradeToV4Note />
-
 ## How to use preview branches

 The preview environment is special – you create branches from it. The branches you create live under the preview environment and have all the features you're used to from other environments (like staging or production). That means you can trigger runs, have schedules, test them, use Realtime, etc.
@@ -101,7 +96,7 @@ jobs:
        run: npm install

      - name: Deploy preview branch
-        run: npx trigger.dev@v4-beta deploy --env preview
+        run: npx trigger.dev@latest deploy --env preview
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
 ```
@@ -121,13 +116,13 @@ You can manually specify the branch using `--branch <branch-name>` in the deploy
 Creating and deploying a preview branch manually is easy:

 ```bash
-npx trigger.dev@v4-beta deploy --env preview
+npx trigger.dev@latest deploy --env preview
 ```

 This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:

 ```bash
-npx trigger.dev@v4-beta deploy --env preview --branch your-branch-name
+npx trigger.dev@latest deploy --env preview --branch your-branch-name
 ```

 ### Archiving a preview branch
@@ -135,7 +130,7 @@ npx trigger.dev@v4-beta deploy --env preview --branch your-branch-name
 You can manually archive a preview branch with the CLI:

 ```bash
-npx trigger.dev@v4-beta preview archive
+npx trigger.dev@latest preview archive
 ```

 Again we will try auto-detect the current branch. But you can specify the branch name with `--branch <branch-name>`.
@@ -10,11 +10,7 @@
  },
  "favicon": "/images/favicon.png",
  "contextual": {
-    "options": [
-      "copy",
-      "view",
-      "claude"
-    ]
+    "options": ["copy", "view", "claude"]
  },
  "navigation": {
    "dropdowns": [
@@ -32,7 +28,7 @@
              "video-walkthrough",
              "how-it-works",
              "limits",
-              "upgrade-to-v4"
+              "migrating-from-v3"
            ]
          },
          {
@@ -40,11 +36,7 @@
            "pages": [
              {
                "group": "Tasks",
-                "pages": [
-                  "tasks/overview",
-                  "tasks/schemaTask",
-                  "tasks/scheduled"
-                ]
+                "pages": ["tasks/overview", "tasks/schemaTask", "tasks/scheduled"]
              },
              "triggering",
              "runs",
@@ -59,12 +51,7 @@
              "errors-retrying",
              {
                "group": "Wait",
-                "pages": [
-                  "wait",
-                  "wait-for",
-                  "wait-until",
-                  "wait-for-token"
-                ]
+                "pages": ["wait", "wait-for", "wait-until", "wait-for-token"]
              },
              "queue-concurrency",
              "versioning",
@@ -74,7 +61,9 @@
              "tags",
              "runs/metadata",
              "run-usage",
-              "context"
+              "context",
+              "runs/priority",
+              "hidden-tasks"
            ]
          },
          {
@@ -110,9 +99,7 @@
          },
          {
            "group": "Development",
-            "pages": [
-              "cli-dev"
-            ]
+            "pages": ["cli-dev"]
          },
          {
            "group": "Deployment",
@@ -124,9 +111,7 @@
              "deployment/atomic-deployment",
              {
                "group": "Deployment integrations",
-                "pages": [
-                  "vercel-integration"
-                ]
+                "pages": ["vercel-integration"]
              }
            ]
          },
@@ -144,7 +129,8 @@
                  "realtime/react-hooks/triggering",
                  "realtime/react-hooks/subscribe",
                  "realtime/react-hooks/streams",
-                  "realtime/react-hooks/swr"
+                  "realtime/react-hooks/swr",
+                  "realtime/react-hooks/use-wait-token"
                ]
              },
              {
@@ -181,12 +167,7 @@
          },
          {
            "group": "Using the Dashboard",
-            "pages": [
-              "run-tests",
-              "troubleshooting-alerts",
-              "replaying",
-              "bulk-actions"
-            ]
+            "pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"]
          },
          {
            "group": "Troubleshooting",
@@ -208,39 +189,19 @@
              "self-hosting/kubernetes",
              {
                "group": "Environment variables",
-                "pages": [
-                  "self-hosting/env/webapp",
-                  "self-hosting/env/supervisor"
-                ]
-              }
-            ],
-            "tags": [
-              "v4"
-            ],
-            "tag": "v4"
-          },
-          {
-            "group": "Self-hosting",
-            "pages": [
+                "pages": ["self-hosting/env/webapp", "self-hosting/env/supervisor"]
+              },
              "open-source-self-hosting"
            ]
          },
+
          {
            "group": "Open source",
-            "pages": [
-              "open-source-contributing",
-              "github-repo",
-              "changelog",
-              "roadmap"
-            ]
+            "pages": ["open-source-contributing", "github-repo", "changelog", "roadmap"]
          },
          {
            "group": "Help",
-            "pages": [
-              "community",
-              "help-slack",
-              "help-email"
-            ]
+            "pages": ["community", "help-slack", "help-email"]
          }
        ]
      },
@@ -261,10 +222,7 @@
          },
          {
            "group": "Tasks API",
-            "pages": [
-              "management/tasks/trigger",
-              "management/tasks/batch-trigger"
-            ]
+            "pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
          },
          {
            "group": "Runs API",
@@ -310,9 +268,7 @@
        "groups": [
          {
            "group": "Introduction",
-            "pages": [
-              "guides/introduction"
-            ]
+            "pages": ["guides/introduction"]
          },
          {
            "group": "Frameworks",
@@ -429,9 +385,7 @@
          },
          {
            "group": "Migration guides",
-            "pages": [
-              "migration-mergent"
-            ]
+            "pages": ["migration-mergent"]
          },
          {
            "group": "Community packages",
@@ -452,10 +406,7 @@
    "href": "https://trigger.dev"
  },
  "api": {
-    "openapi": [
-      "openapi.yml",
-      "v3-openapi.yaml"
-    ],
+    "openapi": ["openapi.yml", "v3-openapi.yaml"],
    "playground": {
      "display": "simple"
    }
@@ -668,6 +619,10 @@
    {
      "source": "/management/projects/runs",
      "destination": "/management/overview"
+    },
+    {
+      "source": "/upgrade-to-v4",
+      "destination": "/migrating-from-v3"
    }
  ]
-}
+}
@@ -31,7 +31,7 @@ This task will retry 10 times with exponential backoff.
 One way to gain reliability is to break your work into smaller tasks and [trigger](/triggering) them from each other. Each task can have its own retrying behavior:

 ```ts /trigger/multiple-tasks.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 export const myTask = task({
  id: "my-task",
@@ -70,7 +70,7 @@ We provide some useful functions that you can use to retry smaller parts of a ta
 You can retry a block of code that can throw an error, with the same retry settings as a task.

 ```ts /trigger/retry-on-throw.ts
-import { task, logger, retry } from "@trigger.dev/sdk/v3";
+import { task, logger, retry } from "@trigger.dev/sdk";

 export const retryOnThrow = task({
  id: "retry-on-throw",
@@ -106,7 +106,7 @@ You can use `fetch`, `axios`, or any other library in your code.
 But we do provide a convenient function to perform HTTP requests with conditional retrying based on the response:

 ```ts /trigger/retry-fetch.ts
-import { task, logger, retry } from "@trigger.dev/sdk/v3";
+import { task, logger, retry } from "@trigger.dev/sdk";

 export const taskWithFetchRetries = task({
  id: "task-with-fetch-retries",
@@ -203,7 +203,7 @@ In this complicated example:
 <CodeGroup>

 ```ts tasks.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { calculateISO8601DurationOpenAIVariantResetAt, openai } from "./openai.js";

 export const openaiTask = task({
@@ -309,7 +309,7 @@ export function calculateISO8601DurationOpenAIVariantResetAt(
 You can prevent retries by throwing an `AbortTaskRunError`. This will fail the task attempt and disable retrying.

 ```ts /trigger/myTasks.ts
-import { task, AbortTaskRunError } from "@trigger.dev/sdk/v3";
+import { task, AbortTaskRunError } from "@trigger.dev/sdk";

 export const openaiTask = task({
  id: "openai-task",
@@ -335,7 +335,7 @@ export const openaiTask = task({
 Sometimes you want to catch an error and don't want to retry the task. You can use try/catch as you normally would. In this example we fallback to using Replicate if OpenAI fails.

 ```ts /trigger/myTasks.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 export const openaiTask = task({
  id: "openai-task",
@@ -24,7 +24,7 @@ In this example, we'll create a workflow that generates and translates copy. Thi

 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { generateText } from "ai";

 export interface TranslatePayload {
@@ -23,7 +23,7 @@ In this example, we'll create a workflow that simultaneously checks content for

 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { batch, task } from "@trigger.dev/sdk/v3";
+import { batch, task } from "@trigger.dev/sdk";
 import { generateText } from "ai";

 // Task to generate customer response
@@ -24,7 +24,7 @@ In this example, we'll create a workflow that routes a question to a different A

 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { generateText } from "ai";
 import { z } from "zod";

@@ -23,7 +23,7 @@ This example task translates text into a target language and refines the transla
 - Recursively calls itself to refine the translation based on the feedback

 ```typescript
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { generateText } from "ai";
 import { openai } from "@ai-sdk/openai";

@@ -26,7 +26,7 @@ Our example task uses multiple LLM calls to extract claims from a news article a

 ```typescript
 import { openai } from "@ai-sdk/openai";
-import { batch, logger, task } from "@trigger.dev/sdk/v3";
+import { batch, logger, task } from "@trigger.dev/sdk";
 import { CoreMessage, generateText } from "ai";

 // Define types for our workers' outputs
@@ -2,11 +2,8 @@
 title: "Human-in-the-loop workflow with ReactFlow and Trigger.dev waitpoint tokens"
 sidebarTitle: "Human-in-the-loop workflow"
 description: "This example project creates audio summaries of newspaper articles using a human-in-the-loop workflow built with ReactFlow and Trigger.dev waitpoint tokens."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
 ## Overview

 This demo is a full stack example that uses the following:
@@ -77,8 +74,6 @@ await wait.completeToken<ReviewPayload>(
 );
 ```

-<UpgradeToV4Note />
-
 While the workflow in this example is static and does not allow changing the connections between nodes in the UI, it serves as a good baseline for understanding how to build completely custom workflow builders using Trigger.dev and ReactFlow.

 ## Learn more about Trigger.dev Realtime and waitpoint tokens
@@ -2,13 +2,8 @@
 title: "Mastra agents with memory sharing + Trigger.dev task orchestration"
 sidebarTitle: "Mastra agents with memory"
 description: "Multi-agent workflow with persistent memory sharing using Mastra and Trigger.dev for clothing recommendations based on weather data."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
-<UpgradeToV4Note />
-
 ## Overview

 Enter a city and an activity, and get a clothing recommendation generated for you based on today's weather.
@@ -2,13 +2,8 @@
 title: "Meme generator with human-in-the-loop approval"
 sidebarTitle: "AI meme generator"
 description: "This example project creates memes using OpenAI's DALL-E 3 with a human-in-the-loop approval workflow built using Trigger.dev waitpoint tokens."
-tag: "v4"
 ---

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
-<UpgradeToV4Note />
-
 ## Overview

 This demo is a full stack example that uses the following:
@@ -2,7 +2,6 @@
 title: "OpenAI Agents SDK for Typescript + Trigger.dev playground"
 sidebarTitle: "OpenAI Agents SDK for Typescript playground"
 description: "Build production-ready AI agents with OpenAI Agents SDK for Typescript and Trigger.dev. Explore 7 examples covering streaming, multi-agent systems, and tool integration."
-tag: "v4"
 ---

 ## Overview
@@ -2,15 +2,10 @@
 title: "Deep research agent using Vercel's AI SDK"
 sidebarTitle: "Deep research agent"
 description: "Deep research agent which generates comprehensive PDF reports using Vercel's AI SDK."
-tag: "v4"
 ---

 import RealtimeLearnMore from "/snippets/realtime-learn-more.mdx";

-import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
-
-<UpgradeToV4Note />
-
 <Info title="Acknowledgements">
  Acknowledgements: This example project is derived from the brilliant [deep research
  guide](https://aie-feb-25.vercel.app/docs/deep-research) by [Nico
@@ -11,7 +11,7 @@ This example demonstrates how to use Trigger.dev to make reliable calls to AI AP
 ## Task code

 ```ts trigger/generateContent.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import OpenAI from "openai";

 const openai = new OpenAI({
@@ -17,7 +17,7 @@ Transcribe audio using [Deepgram's](https://developers.deepgram.com/docs/introdu

 ```ts trigger/deepgramTranscription.ts
 import { createClient } from "@deepgram/sdk";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";

 // Initialize the Deepgram client, using your Deepgram API key (you can find this in your Deepgram account settings).
 const deepgram = createClient(process.env.DEEPGRAM_SECRET_KEY);
@@ -30,7 +30,7 @@ This video walks through the process of creating this task in a Next.js project.
 This task converts an image to a cartoon using Fal.ai, and uploads the result to Cloudflare R2.

 ```ts trigger/fal-ai-image-to-cartoon.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import * as fal from "@fal-ai/serverless-client";
 import fetch from "node-fetch";
@@ -41,7 +41,7 @@ This task generates an image from a prompt using Fal.ai.

 ```ts trigger/fal-ai-image-from-prompt-realtime.ts
 import * as fal from "@fal-ai/serverless-client";
-import { logger, schemaTask } from "@trigger.dev/sdk/v3";
+import { logger, schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";

 export const FalResult = z.object({
@@ -17,7 +17,7 @@ To use these example tasks, you'll first need to add our FFmpeg extension to you

 ```ts trigger.config.ts
 import { ffmpeg } from "@trigger.dev/build/extensions/core";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -52,7 +52,7 @@ This task demonstrates how to use FFmpeg to compress a video, reducing its file

 ```ts trigger/ffmpeg-compress-video.ts
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import ffmpeg from "fluent-ffmpeg";
 import fs from "fs/promises";
 import fetch from "node-fetch";
@@ -164,7 +164,7 @@ This task demonstrates how to use FFmpeg to extract audio from a video, convert

 ```ts trigger/ffmpeg-extract-audio.ts
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import ffmpeg from "fluent-ffmpeg";
 import fs from "fs/promises";
 import fetch from "node-fetch";
@@ -277,7 +277,7 @@ This task demonstrates how to use FFmpeg to generate a thumbnail from a video at

 ```ts trigger/ffmpeg-generate-thumbnail.ts
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import ffmpeg from "fluent-ffmpeg";
 import fs from "fs/promises";
 import fetch from "node-fetch";
@@ -21,7 +21,7 @@ This task crawls a website and returns the `crawlResult` object. You can set the

 ```ts trigger/firecrawl-url-crawl.ts
 import FirecrawlApp from "@mendable/firecrawl-js";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 // Initialize the Firecrawl client with your API key
 const firecrawlClient = new FirecrawlApp({
@@ -66,7 +66,7 @@ This task scrapes a single URL and returns the `scrapeResult` object.

 ```ts trigger/firecrawl-url-scrape.ts
 import FirecrawlApp, { ScrapeResponse } from "@mendable/firecrawl-js";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 // Initialize the Firecrawl client with your API key
 const firecrawlClient = new FirecrawlApp({
@@ -18,7 +18,7 @@ To deploy this task, you'll need to add LibreOffice to your project configuratio

 ```ts trigger.config.ts
 import { aptGet } from "@trigger.dev/build/extensions/core";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -55,7 +55,7 @@ This task demonstrates how to use LibreOffice to convert a document (.doc or .do

 ```ts trigger/libreoffice-pdf-convert.ts
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import libreoffice from "libreoffice-convert";
 import { promisify } from "node:util";
 import path from "path";
@@ -11,7 +11,7 @@ Sometimes OpenAI calls can take a long time to complete, or they can fail. This
 ## Task code

 ```ts trigger/openai.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import OpenAI from "openai";

 const openai = new OpenAI({
@@ -27,7 +27,7 @@ export default defineConfig({
 ## Task code

 ```ts trigger/pdfToImage.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import { execSync } from "child_process";
 import fs from "fs";
@@ -27,7 +27,7 @@ There are 3 example tasks to follow on this page:
 To use all examples on this page, you'll first need to add these build settings to your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";

 export default defineConfig({
@@ -59,7 +59,7 @@ In this example we use [Puppeteer](https://pptr.dev/) to log out the title of a
 ### Task code

 ```ts trigger/puppeteer-basic-example.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import puppeteer from "puppeteer";

 export const puppeteerTask = task({
@@ -91,7 +91,7 @@ In this example we use [Puppeteer](https://pptr.dev/) to generate a PDF from the
 ### Task code

 ```ts trigger/puppeteer-generate-pdf.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import puppeteer from "puppeteer";
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

@@ -158,7 +158,7 @@ In this example we use [Puppeteer](https://pptr.dev/) with a [BrowserBase](https
 ### Task code

 ```ts trigger/scrape-website.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import puppeteer from "puppeteer-core";

 export const puppeteerScrapeWithProxy = task({
@@ -23,7 +23,7 @@ This example demonstrates how to use Trigger.dev to send emails using [React Ema

 ```tsx trigger/sendReactEmail.tsx
 import { Body, Button, Container, Head, Heading, Html, Preview } from "@react-email/components";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { Resend } from "resend";

 // Initialize Resend client
@@ -293,7 +293,7 @@ const footer = {
 And then to trigger the email, you can use the following task:

 ```tsx trigger/triggerWelcomeEmail.tsx
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { Resend } from "resend";
 import TriggerWelcomeEmail from "emails/trigger-welcome-email";

@@ -13,7 +13,7 @@ This example demonstrates how to use Trigger.dev to generate a PDF using [react-
 <Info> This example must be a .tsx file to use React components.</Info>

 ```ts trigger/generateResumePDF.tsx
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { renderToBuffer, Document, Page, Text, View } from "@react-pdf/renderer";
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

@@ -13,7 +13,7 @@ This can be customized and extended however you like, full list of options can b
 ## Task code

 ```tsx trigger/generateOgImage.ts
-import { schemaTask } from "@trigger.dev/sdk/v3";
+import { schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";
 import satori from "satori";
 import sharp from "sharp";
@@ -50,7 +50,7 @@ And we'll be using the following tools and features:
 First up, add these build settings to your `trigger.config.ts` file:

 ```tsx trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";

 export default defineConfig({
@@ -79,7 +79,7 @@ RESEND_API_KEY: "<your Resend API key>"

 ```ts trigger/scrape-hacker-news.ts
 import { render } from "@react-email/render";
-import { logger, schedules, task, wait } from "@trigger.dev/sdk/v3";
+import { logger, schedules, task, wait } from "@trigger.dev/sdk";
 import { OpenAI } from "openai";
 import puppeteer from "puppeteer-core";
 import { Resend } from "resend";
@@ -26,7 +26,7 @@ To send errors to Sentry when there are errors in your tasks, you'll need to add
 </Note>

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { esbuildPlugin } from "@trigger.dev/build/extensions";
 import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";
 import * as Sentry from "@sentry/node";
@@ -80,7 +80,7 @@ To test that errors are being sent to Sentry, you need to create a task that wil
 This task takes no payload, and will throw an error.

 ```ts trigger/sentry-error-test.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 export const sentryErrorTest = task({
  id: "sentry-error-test",
@@ -21,7 +21,7 @@ This task processes and watermarks an image using the Sharp library, and then up
 To use this example, you'll first need to add these build settings to your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -49,7 +49,7 @@ export default defineConfig({
 ```ts trigger/sharp-image-processing.ts
 import { S3Client } from "@aws-sdk/client-s3";
 import { Upload } from "@aws-sdk/lib-storage";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import fs from "fs/promises";
 import os from "os";
 import path from "path";
@@ -32,7 +32,7 @@ Here are examples of how you can set up a handler using different frameworks:
 ```ts Next.js
 // app/api/stripe-webhook/route.ts
 import { NextResponse } from "next/server";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import Stripe from "stripe";
 import type { stripeCheckoutCompleted } from "@/trigger/stripe-checkout-completed";
 //     👆 **type-only** import
@@ -84,7 +84,7 @@ export async function POST(request: Request) {
 import { type ActionFunctionArgs, json } from "@remix-run/node";
 import type { stripeCheckoutCompleted } from "src/trigger/stripe-webhook";
 //     👆 **type-only** import
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import Stripe from "stripe";

 export async function action({ request }: ActionFunctionArgs) {
@@ -127,7 +127,7 @@ export async function action({ request }: ActionFunctionArgs) {
 This task is triggered when a `checkout.session.completed` event is received from Stripe.

 ```ts trigger/stripe-checkout-completed.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import type stripe from "stripe";

 export const stripeCheckoutCompleted = task({
@@ -27,7 +27,7 @@ This is a basic task which inserts a new row into a table from a Trigger.dev tas

 ```ts trigger/supabase-database-insert.ts
 import { createClient } from "@supabase/supabase-js";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import jwt from "jsonwebtoken";
 // Generate the Typescript types using the Supabase CLI: https://supabase.com/docs/guides/api/rest/generating-types
 import { Database } from "database.types";
@@ -117,7 +117,7 @@ This type of task is useful for managing user subscriptions, updating user detai

 ```ts trigger/supabase-update-user-subscription.ts
 import { createClient } from "@supabase/supabase-js";
-import { AbortTaskRunError, task } from "@trigger.dev/sdk/v3";
+import { AbortTaskRunError, task } from "@trigger.dev/sdk";
 // Generate the Typescript types using the Supabase CLI: https://supabase.com/docs/guides/api/rest/generating-types
 import { Database } from "database.types";

@@ -22,7 +22,7 @@ This task downloads a video from a provided URL and uploads it to Supabase Stora

 ```ts trigger/supabase-storage-upload.ts
 import { createClient } from "@supabase/supabase-js";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import fetch from "node-fetch";

 // Initialize Supabase client
@@ -92,7 +92,7 @@ This task downloads a video from a provided URL, saves it to a temporary file, a

 ```ts trigger/supabase-storage-upload-s3.ts
 import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import fetch from "node-fetch";

 // Initialize S3 client for Supabase Storage
@@ -19,7 +19,7 @@ This task shows how to use the Vercel AI SDK to generate text from a prompt with
 ### Task code

 ```ts trigger/vercel-ai-sdk-openai.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { generateText } from "ai";
 // Install the package of the AI model you want to use, in this case OpenAI
 import { openai } from "@ai-sdk/openai"; // Ensure OPENAI_API_KEY environment variable is set
@@ -20,7 +20,7 @@ To sync environment variables, you just need to add our build extension to your
 </Note>

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -62,7 +62,7 @@ Install the "Hello World" example task when prompted. We'll use this task to tes

    ```ts example.ts
    import { Database } from "bun:sqlite";
-    import { task } from "@trigger.dev/sdk/v3";
+    import { task } from "@trigger.dev/sdk";

    export const bunTask = task({
      id: "bun-task",
@@ -51,7 +51,7 @@ This is a simple task that will add a new user to your database, we will call it

 ```ts /trigger/drizzle-add-new-user.ts
 import { eq } from "drizzle-orm";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { users } from "src/db/schema";
 import { drizzle } from "drizzle-orm/node-postgres";

@@ -80,7 +80,7 @@ Next, in your `trigger.config.js` file, add `pg` to the `externals` array. `pg`
 It is marked as an external to ensure that it is not bundled into the task's bundle, and instead will be installed and loaded from `node_modules` at runtime.

 ```js /trigger.config.js
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>", // Your project reference
@@ -36,7 +36,7 @@ In your new file, add the following code:

 ```ts /pages/api/webhook-handler.ts
 import { helloWorldTask } from "@/trigger/example";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import type { NextApiRequest, NextApiResponse } from "next";

 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
@@ -60,7 +60,7 @@ In your new file, add the following code:

 ```ts /app/api/webhook-handler/route.ts
 import type { helloWorldTask } from "@/trigger/example";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import { NextResponse } from "next/server";

 export async function POST(req: Request) {
@@ -67,7 +67,7 @@ Here are the steps to trigger your task in the Next.js App and Pages router and
      ```ts app/api/hello-world/route.ts
      // Next.js API route support: https://nextjs.org/docs/api-routes/introduction
      import type { helloWorldTask } from "@/trigger/example";
-      import { tasks } from "@trigger.dev/sdk/v3";
+      import { tasks } from "@trigger.dev/sdk";
      import { NextResponse } from "next/server";

      //tasks.trigger also works with the edge runtime
@@ -107,7 +107,7 @@ Here are the steps to trigger your task in the Next.js App and Pages router and
        "use server";

        import type { helloWorldTask } from "@/trigger/example";
-        import { tasks } from "@trigger.dev/sdk/v3";
+        import { tasks } from "@trigger.dev/sdk";

        export async function myTask() {
          try {
@@ -220,7 +220,7 @@ Here are the steps to trigger your task in the Next.js App and Pages router and
      ```ts pages/api/hello-world.ts
      // Next.js API route support: https://nextjs.org/docs/api-routes/introduction
      import { helloWorldTask } from "@/trigger/example";
-      import { tasks } from "@trigger.dev/sdk/v3";
+      import { tasks } from "@trigger.dev/sdk";
      import type { NextApiRequest, NextApiResponse } from "next";

      export default async function handler(
@@ -263,7 +263,7 @@ If you want to automatically sync environment variables from your Vercel project
 </Note>

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -370,7 +370,7 @@ To run this task in production, you will need to set the `REVALIDATION_SECRET` e
 </Note>

 ```ts trigger/revalidate-path.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";

 const NEXTJS_APP_URL = process.env.NEXTJS_APP_URL; // e.g. "http://localhost:3000" or "https://my-nextjs-app.vercel.app"
 const REVALIDATION_SECRET = process.env.REVALIDATION_SECRET; // Create a REVALIDATION_SECRET and set it in your environment variables
@@ -51,7 +51,7 @@ This is a simple task that will add a new user to the database.

 ```ts /trigger/prisma-add-new-user.ts
 import { PrismaClient } from "@prisma/client";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 // Initialize Prisma client
 const prisma = new PrismaClient();
@@ -117,7 +117,7 @@ We use OpenTelemetry to [instrument](https://trigger.dev/docs/config/config-file
 If you want to automatically log all Prisma queries and mutations, you can use the Prisma instrumentation extension.

 ```js /trigger.config.js
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { PrismaInstrumentation } from "@prisma/instrumentation";
 import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";

@@ -28,7 +28,7 @@ In your new file, add the following code:

 ```ts /api/webhook-handler.ts
 import type { ActionFunctionArgs } from "@remix-run/node";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import { helloWorldTask } from "src/trigger/example";

 export async function action({ request }: ActionFunctionArgs) {
@@ -50,7 +50,7 @@ Add this code to your `api.hello-world.ts` file which imports your task:

 ```ts app/routes/api.hello-world.ts
 import type { helloWorldTask } from "../../src/trigger/example";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";

 export async function loader() {
  const handle = await tasks.trigger<typeof helloWorldTask>("hello-world", "James");
@@ -80,7 +80,7 @@ export async function loader() {
 Before we start, it's important to note that:

 - We'll be using a type-only import for the task to ensure compatibility with the edge runtime.
- The `@trigger.dev/sdk/v3` package supports the edge runtime out of the box.
+- The `@trigger.dev/sdk` package supports the edge runtime out of the box.

 There are a few extra steps to follow to deploy your `/api/hello-world` API endpoint to Vercel Edge Functions.

@@ -91,7 +91,7 @@ There are a few extra steps to follow to deploy your `/api/hello-world` API endp
 Update your API route to use the `runtime: "edge"` option and change it to an `action()` so we can trigger the task from a curl request later on.

 ```ts app/routes/api.hello-world.ts
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import type { helloWorldTask } from "../../src/trigger/example";
 //      👆 **type-only** import

@@ -40,7 +40,7 @@ Start by creating a new Trigger.dev task that takes in a Sequin change event as

  <CodeGroup>
  ```ts trigger/create-embedding-for-post.ts
-  import { task } from "@trigger.dev/sdk/v3";
+  import { task } from "@trigger.dev/sdk";
  import { OpenAI } from "openai";
  import { upsertEmbedding } from "../util";

@@ -161,7 +161,7 @@ You'll now create an API endpoint that will receive posts from Sequin and then t

 ```ts app/api/create-embedding-for-post/route.ts
 import type { createEmbeddingForPost } from "@/trigger/create-embedding-for-post";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import { NextResponse } from "next/server";

 export async function POST(req: Request) {
@@ -147,7 +147,7 @@ These dependencies will allow you to interact with the Deepgram and Supabase API
 // Install any missing dependencies below
 import { createClient as createDeepgramClient } from "@deepgram/sdk";
 import { createClient as createSupabaseClient } from "@supabase/supabase-js";
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import ffmpeg from "fluent-ffmpeg";
 import fs from "fs";
 import { Readable } from "node:stream";
@@ -255,7 +255,7 @@ Before you can deploy the task, you'll need to add the FFmpeg build extension to
 ```ts trigger.config.ts
 // Add this import
 import { ffmpeg } from "@trigger.dev/build/extensions/core";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>", // Replace with your project ref
@@ -47,10 +47,10 @@ The new build system does not effect your trigger task files at all, so those ca

 ### `defineConfig`

-You should now import the `defineConfig` function from `@trigger.dev/sdk/v3` and export the config as the default export:
+You should now import the `defineConfig` function from `@trigger.dev/sdk` and export the config as the default export:

 ```
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -66,7 +66,7 @@ The new build system will bundle all dependencies by default, so `dependenciesTo
 Now that all dependencies are bundled, there are some situations where bundling a dependency doesn't work, and needs to be made external (e.g. when a dependency includes a native module). You can now specify these dependencies as build externals in the `defineConfig` function:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  project: "<project ref>",
@@ -91,7 +91,7 @@ npm add @trigger.dev/build@0.0.0-prerelease-20240911144933 -D
 Now you can import the `additionalFiles` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { additionalFiles } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -117,7 +117,7 @@ npm add @trigger.dev/build@0.0.0-prerelease-20240911144933 -D
 Now you can import the `additionalPackages` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { additionalPackages } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -141,7 +141,7 @@ npm add @trigger.dev/build@0.0.0-prerelease-20240911144933 -D
 Now you can import the `syncEnvVars` build extension and use it in your `trigger.config.ts` file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";

 export default defineConfig({
@@ -167,7 +167,7 @@ One other difference is now `params.env` only contains the environment variables
 If you make use of decorators in your code, and have enabled the `emitDecoratorMetadata` tsconfig compiler option, you'll need to enable this in the new build sytem using the `emitDecoratorMetadata` build extension:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";

 export default defineConfig({
@@ -189,7 +189,7 @@ npm add @trigger.dev/build@0.0.0-prerelease-20240911144933 -D
 Then you can import the `prismaExtension` build extension and use it in your `trigger.config.ts` file, passing in the path to your Prisma schema file:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -214,7 +214,7 @@ This will make sure that your prisma client is generated during the build proces
 If you want to also run migrations during the build process, you can pass in the `migrate` option:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -256,7 +256,7 @@ generator kysely {
 ```

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

 export default defineConfig({
@@ -279,7 +279,7 @@ export default defineConfig({
 Previously, we installed [Audio Waveform](https://github.com/bbc/audiowaveform) in the build image. That's been moved to a build extension:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";

 export default defineConfig({
@@ -295,7 +295,7 @@ export default defineConfig({
 You can now add esbuild plugins to customize the build process using the `esbuildPlugin` build extension. The example below shows how to automatically upload sourcemaps to Sentry using their esbuild plugin:

 ```ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { esbuildPlugin } from "@trigger.dev/build/extensions";
 import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";

@@ -60,7 +60,7 @@ Once you have a proxy service, set the following environment variables in your T
 After you've initialized your project with Trigger.dev, add these build settings to your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { pythonExtension } from "@trigger.dev/python/extension";
 import type { BuildContext, BuildExtension } from "@trigger.dev/core/v3/build";

@@ -123,7 +123,7 @@ export function installPlaywrightChromium(): BuildExtension {
 This task uses the `python.runScript` method to run the `crawl-url.py` script with the given URL as an argument. You can see the original task in our examples repository [here](https://github.com/triggerdotdev/examples/blob/main/python-crawl4ai/src/trigger/pythonTasks.ts).

 ```ts src/trigger/pythonTasks.ts
-import { logger, schemaTask, task } from "@trigger.dev/sdk/v3";
+import { logger, schemaTask, task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";
 import { z } from "zod";

@@ -6,11 +6,6 @@ description: "Learn how to use Trigger.dev with Python to convert documents to m

 import PythonLearnMore from "/snippets/python-learn-more.mdx";

-<Note>
-  This project uses Trigger.dev v4 (which is currently in beta as of 28 April 2025). If you want to
-  run this project you will need to [upgrade to v4](/upgrade-to-v4).
-</Note>
-
 ## Overview

 Convert documents to markdown using Microsoft's [MarkItDown](https://github.com/microsoft/markitdown) library. This can be especially useful for preparing documents in a structured format for AI applications.
@@ -45,7 +40,7 @@ After you've initialized your project with Trigger.dev, add these build settings

 ```ts trigger.config.ts
 import { pythonExtension } from "@trigger.dev/python/extension";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  runtime: "node",
@@ -76,7 +71,7 @@ export default defineConfig({
 This task uses the `python.runScript` method to run the `markdown-converter.py` script with the given document URL as an argument.

 ```ts src/trigger/convertToMarkdown.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";
 import * as fs from "fs";
 import * as path from "path";
@@ -42,7 +42,7 @@ After you've initialized your project with Trigger.dev, add these build settings

 ```ts trigger.config.ts
 import { pythonExtension } from "@trigger.dev/python/extension";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  runtime: "node",
@@ -73,7 +73,7 @@ export default defineConfig({
 This task uses the `python.runScript` method to run the `image-processing.py` script with the given image URL as an argument. You can adjust the image processing parameters in the payload, with options such as height, width, quality, output format, etc.

 ```ts src/trigger/processImage.ts
-import { schemaTask } from "@trigger.dev/sdk/v3";
+import { schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";
 import { python } from "@trigger.dev/python";
 import { promises as fs } from "fs";
@@ -41,7 +41,7 @@ After you've initialized your project with Trigger.dev, add these build settings

 ```ts trigger.config.ts
 import { pythonExtension } from "@trigger.dev/python/extension";
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";

 export default defineConfig({
  runtime: "node",
@@ -72,7 +72,7 @@ export default defineConfig({
 This task uses the `python.runScript` method to run the `image-processing.py` script with the given image URL as an argument. You can adjust the image processing parameters in the payload, with options such as height, width, quality, output format, etc.

 ```ts src/trigger/pythonPdfTask.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { python } from "@trigger.dev/python";

 export const processPdfForm = task({
@@ -59,7 +59,7 @@ client.defineJob({
 In v3 it looks like this:

 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 import { db } from "@/lib/db";
 export const getCreatorVideosFromTikTok = task({
  id: "my-job-id",
@@ -136,7 +136,7 @@ export const openaiJob = task({
 So don't use the `@trigger.dev/openai` package in v3, use the official OpenAI SDK.
 Bear in mind that the syntax for the latest official SDK will probably be different from the @trigger.dev integration SDK. You will need to adapt the code accordingly.
 3. The most critical difference is that inside the `run` function you do NOT need to wrap everything in `io.runTask`. So anything inside there can be extracted out and be used in the main body of the function without wrapping it.
-4. The import for `task` in v3 is `import { task } from "@trigger.dev/sdk/v3";`
+4. The import for `task` in v3 is `import { task } from "@trigger.dev/sdk";`
 5. You can trigger jobs from other jobs. In v2 this was typically done by either calling `io.sendEvent()` or by calling `yourOtherTask.invoke()`. In v3 you call `.trigger()` on the other task, there are no events in v3.
 v2:

@@ -258,7 +258,7 @@ client.defineJob({
 In v3 we eliminate a lot of code mainly because we don't need tricks to try avoid timeouts. Here's the equivalent v3 code:

 ```ts v3 OpenAI task
-import { logger, task, wait } from "@trigger.dev/sdk/v3";
+import { logger, task, wait } from "@trigger.dev/sdk";

 //1. Official OpenAI SDK
 import OpenAI from "openai";
@@ -0,0 +1,56 @@
+---
+title: "Hidden tasks"
+description: "Create tasks that are not exported from your trigger files but can still be executed."
+---
+
+Hidden tasks are tasks that are not exported from your trigger files but can still be executed. These tasks are only accessible to other tasks within the same file or module where they're defined.
+
+```ts trigger/my-task.ts
+import { task } from "@trigger.dev/sdk";
+
+// This is a hidden task - not exported
+const internalTask = task({
+  id: "internal-processing",
+  run: async (payload: any, { ctx }) => {
+    // Internal processing logic
+  },
+});
+```
+
+Hidden tasks are useful for creating internal workflows that should only be triggered by other tasks in the same file:
+
+```ts trigger/my-workflow.ts
+import { task } from "@trigger.dev/sdk";
+
+// Hidden task for internal use
+const processData = task({
+  id: "process-data",
+  run: async (payload: { data: string }, { ctx }) => {
+    // Process the data
+    return { processed: payload.data.toUpperCase() };
+  },
+});
+
+// Public task that uses the hidden task
+export const mainWorkflow = task({
+  id: "main-workflow",
+  run: async (payload: any, { ctx }) => {
+    const result = await processData.trigger({ data: payload.input });
+    return result;
+  },
+});
+```
+
+You can also create packages of reusable tasks that can be imported and used without needing to re-export them:
+
+```ts trigger/my-task.ts
+import { task } from "@trigger.dev/sdk";
+import { sendToSlack } from "@repo/tasks"; // Hidden task from another package
+
+export const notificationTask = task({
+  id: "send-notification",
+  run: async (payload: any, { ctx }) => {
+    await sendToSlack.trigger(payload);
+  },
+});
+```
@@ -11,7 +11,7 @@ Trigger.dev v3 allows you to integrate long-running async tasks into your applic
 For example, the below task processes a video with `ffmpeg` and sends the results to an s3 bucket, then updates a database with the results and sends an email to the user.

 ```ts /trigger/video.ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";
 import { updateVideoUrl } from "../db.js";
 import ffmpeg from "fluent-ffmpeg";
 import { Readable } from "node:stream";
@@ -85,7 +85,7 @@ Now in your application, you can trigger this task by calling:

 ```ts
 import { NextResponse } from "next/server";
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";
 import type { convertVideo } from "./trigger/video";
 //     👆 **type-only** import

@@ -165,7 +165,7 @@ This approach allows Trigger.dev to manage resources efficiently, handle complex
 Example of a parent and child task using the Checkpoint-Resume System:

 ```ts
-import { task, wait } from "@trigger.dev/sdk/v3";
+import { task, wait } from "@trigger.dev/sdk";

 export const parentTask = task({
  id: "parent-task",
@@ -249,7 +249,7 @@ Let's rewrite the `convert-video` task above to be more durable:
 <CodeGroup>

 ```ts /trigger/video.ts
-import { idempotencyKeys, logger, task } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, logger, task } from "@trigger.dev/sdk";
 import { processVideo, sendUserEmail, uploadToS3 } from "./tasks.js";
 import { updateVideoUrl } from "../db.js";

@@ -287,7 +287,7 @@ export const convertVideo = task({
 ```

 ```ts /trigger/tasks.ts
-import { task, logger } from "@trigger.dev/sdk/v3";
+import { task, logger } from "@trigger.dev/sdk";
 import ffmpeg from "fluent-ffmpeg";
 import { Readable } from "node:stream";
 import type { ReadableStream } from "node:stream/web";
@@ -441,7 +441,7 @@ The Trigger.dev logging and task dashboard is powered by OpenTelemetry traces an
 Because we use standard OpenTelemetry, you can instrument your code and OpenTelemetry compatible libraries to get detailed traces and logs of your tasks. The above trace instruments both Prisma and the AWS SDK:

 ```ts trigger.config.ts
-import { defineConfig } from "@trigger.dev/sdk/v3";
+import { defineConfig } from "@trigger.dev/sdk";
 import { PrismaInstrumentation } from "@prisma/instrumentation";
 import { AwsInstrumentation } from "@opentelemetry/instrumentation-aws-sdk";

@@ -16,7 +16,7 @@ We currently support idempotency at the task level, meaning that if you trigger
 You can provide an `idempotencyKey` to ensure that a task is only triggered once with the same key. This is useful if you are triggering a task within another task that might be retried:

 ```ts
-import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, task } from "@trigger.dev/sdk";

 export const myTask = task({
  id: "my-task",
@@ -41,7 +41,7 @@ You can use the `idempotencyKeys.create` SDK function to create an idempotency k
 We automatically inject the run ID when generating the idempotency key when running inside a task by default. You can turn it off by passing the `scope` option to `idempotencyKeys.create`:

 ```ts
-import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, task } from "@trigger.dev/sdk";

 export const myTask = task({
  id: "my-task",
@@ -61,7 +61,7 @@ export const myTask = task({
 If you are triggering a task from your backend code, you can use the `idempotencyKeys.create` SDK function to create an idempotency key.

 ```ts
-import { idempotencyKeys, tasks } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, tasks } from "@trigger.dev/sdk";

 // You can also pass an array of strings to create a idempotency key
 const idempotencyKey = await idempotencyKeys.create([myUser.id, "my-task"]);
@@ -82,7 +82,7 @@ await myTask.trigger({ some: "data" }, { idempotencyKey: myUser.id });
 You can pass the `idempotencyKey` when calling `batchTrigger` as well:

 ```ts
-import { tasks } from "@trigger.dev/sdk/v3";
+import { tasks } from "@trigger.dev/sdk";

 await tasks.batchTrigger("my-task", [
  {
@@ -105,7 +105,7 @@ The `idempotencyKeyTTL` option defines a time window during which a task with th
 By default idempotency keys are stored for 30 days. You can change this by passing the `idempotencyKeyTTL` option when triggering a task:

 ```ts
-import { idempotencyKeys, task, wait } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, task, wait } from "@trigger.dev/sdk";

 export const myTask = task({
  id: "my-task",
@@ -141,7 +141,7 @@ You can use the following units for the `idempotencyKeyTTL` option:
 We don't currently support payload-based idempotency, but you can implement it yourself by hashing the payload and using the hash as the idempotency key.

 ```ts
-import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
 import { createHash } from "node:crypto";

 // Somewhere in your code
@@ -23,6 +23,8 @@ Generally speaking each SDK call is an API call.
 | :---- | :------------------------ |
 | API   | 1,500 requests per minute |

+You can request a higher rate limit from us if you're on a paid plan.
+
 <RateLimitHitUseBatchTrigger />

 ## Queued tasks
@@ -136,7 +138,7 @@ We limit the size of logs to prevent oversized data potentially causing issues.

 ## Alerts

-An alert destination is a single email address, Slack channel, or webhook URL that you want to send alerts to. 
+An alert destination is a single email address, Slack channel, or webhook URL that you want to send alerts to.

 | Pricing tier | Limit                   |
 | :----------- | :---------------------- |
@@ -160,4 +162,4 @@ See the [machine configurations](/machines#machine-configurations) for more deta
 | Hobby        | 5 team members   |
 | Pro          | 25+ team members |

-Additional seats are available for $20/month per seat. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.
+Additional seats are available for $20/month per seat. Contact us via [email](https://trigger.dev/contact) or [Discord](https://trigger.dev/discord) to request more.
@@ -16,7 +16,7 @@ You can use `console.log()`, `console.error()`, etc as normal and they will be s
 We recommend that you use our `logger` object which creates structured logs. Structured logs will make it easier for you to search the logs to quickly find runs.

 ```ts /trigger/logging.ts
-import { task, logger } from "@trigger.dev/sdk/v3";
+import { task, logger } from "@trigger.dev/sdk";

 export const loggingExample = task({
  id: "logging-example",
@@ -54,7 +54,7 @@ You can [add instrumentations](/config/config-file#instrumentations). The Prisma
 If you want to add custom traces to your code, you can use the `logger.trace` function. It will create a new OTEL trace and you can set attributes on it.

 ```ts
-import { logger, task } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk";

 export const customTrace = task({
  id: "custom-trace",
@@ -6,7 +6,7 @@ description: "Configure the number of vCPUs and GBs of RAM you want the task to
 The `machine` configuration is optional. Using higher spec machines will increase the cost of running the task but can also improve the performance of the task if it is CPU or memory bound.

 ```ts /trigger/heavy-task.ts
-import {  task } from "@trigger.dev/sdk/v3";
+import {  task } from "@trigger.dev/sdk";

 export const heavyTask = task({
  id: "heavy-task",
@@ -20,7 +20,7 @@ export const heavyTask = task({
 The default machine is `small-1x` which has 0.5 vCPU and 0.5 GB of RAM. You can change the default machine in your `trigger.config.ts` file:

 ```ts trigger.config.ts
-import type { TriggerConfig } from "@trigger.dev/sdk/v3";
+import type { TriggerConfig } from "@trigger.dev/sdk";

 export const config: TriggerConfig = {
  machine: "small-2x",
@@ -67,8 +67,8 @@ We automatically detect common Out Of Memory errors, including when ffmpeg throw
 You can explicitly throw an Out Of Memory error in your task. This can be useful if you use a native package that detects it's going to run out of memory and then stops before it runs out. If you can detect this, you can then throw this error.

 ```ts /trigger/heavy-task.ts
-import {  task } from "@trigger.dev/sdk/v3";
-import { OutOfMemoryError } from "@trigger.dev/sdk/v3";
+import {  task } from "@trigger.dev/sdk";
+import { OutOfMemoryError } from "@trigger.dev/sdk";

 export const yourTask = task({
  id: "your-task",
@@ -88,7 +88,7 @@ If OOM errors happen regularly you need to either optimize the memory-efficiency
 If you are seeing rare OOM errors, it might make sense to add a setting to your task to retry with a large machine when an OOM happens:

 ```ts /trigger/heavy-task.ts
-import {  task } from "@trigger.dev/sdk/v3";
+import {  task } from "@trigger.dev/sdk";

 export const yourTask = task({
  id: "your-task",
@@ -9,7 +9,7 @@ description: Advanced usage of the Trigger.dev management API
 All API methods return a `Promise` subclass `ApiPromise` that includes helpers for accessing the underlying HTTP response:

 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 async function main() {
  const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();
@@ -15,7 +15,7 @@ There are two methods of authenticating with the management API: using a secret
 Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the `runs.list` function can be called using either a `secretKey` or a `personalAccessToken`, but the `projectRef` argument is required when using a `personalAccessToken`:

 ```ts
-import { configure, runs } from "@trigger.dev/sdk/v3";
+import { configure, runs } from "@trigger.dev/sdk";

 // Using secretKey authentication
 configure({
@@ -82,7 +82,7 @@ A PAT is a token associated with a specific user, and gives access to all the or
 For example, when uploading environment variables using a PAT, you must provide the `projectRef` and `environment` arguments:

 ```ts
-import { configure, envvars } from "@trigger.dev/sdk/v3";
+import { configure, envvars } from "@trigger.dev/sdk";

 configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
@@ -95,3 +95,66 @@ await envvars.upload("proj_1234", "dev", {
  override: true,
 });
 ```
+
+### Preview branch targeting
+
+When working with preview branches, you may need to target a specific branch when making API calls. This is particularly useful for managing environment variables or other resources that are scoped to individual preview branches.
+
+<Tabs>
+  <Tab title="SDK">
+    To target a specific preview branch, include the `previewBranch` option in your SDK configuration:
+
+```ts
+import { configure, envvars } from "@trigger.dev/sdk";
+
+configure({
+  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  previewBranch: "feature-xyz",
+});
+
+await envvars.update("proj_1234", "preview", "DATABASE_URL", {
+  value: "your_preview_database_url",
+});
+```
+
+  </Tab>
+  <Tab title="cURL">
+    To target a specific preview branch, include the `x-trigger-branch` header in your API requests with the branch name as the value:
+
+```bash
+curl --request PUT \
+  --url https://api.trigger.dev/api/v1/projects/{projectRef}/envvars/preview/DATABASE_URL \
+  --header 'Authorization: Bearer <token>' \
+  --header 'x-trigger-branch: feature-xyz' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "value": "your_preview_database_url"
+  }'
+```
+
+  </Tab>
+</Tabs>
+This will set the `DATABASE_URL` environment variable specifically for the `feature-xyz` preview branch.
+
+<Note>
+  The `x-trigger-branch` header is only relevant when working with the `preview` environment (`{env}
+  ` parameter set to `preview`). It has no effect when working with `dev`, `staging`, or `prod`
+  environments.
+</Note>
+
+#### SDK usage with preview branches
+
+When using the SDK to manage preview branch environment variables, the branch targeting is handled automatically when you're running in a preview environment with the `TRIGGER_PREVIEW_BRANCH` environment variable set. However, you can also specify the branch explicitly:
+
+```ts
+import { configure, envvars } from "@trigger.dev/sdk";
+
+configure({
+  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  previewBranch: "feature-xyz", // Optional: specify the branch
+});
+
+await envvars.update("proj_1234", "preview", "DATABASE_URL", {
+  value: "your_preview_database_url",
+});
+```
@@ -8,7 +8,7 @@ All list endpoints in the management API support auto-pagination.
 You can use `for await … of` syntax to iterate through items across all pages:

 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 async function fetchAllRuns() {
  const allRuns = [];
@@ -24,7 +24,7 @@ async function fetchAllRuns() {
 You can also use helpers on the return value from any `list` method to get the next/previous page of results:

 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 async function main() {
  let page = await runs.list({ limit: 10 });
@@ -9,7 +9,7 @@ description: Handling errors and retries with the Trigger.dev management API
 When the SDK method is unable to connect to the API server, or the API server returns a non-successful response, the SDK will throw an `ApiError` that you can catch and handle:

 ```ts
-import { runs, APIError } from "@trigger.dev/sdk/v3";
+import { runs, APIError } from "@trigger.dev/sdk";

 async function main() {
  try {
@@ -31,7 +31,7 @@ The SDK will automatically retry requests that fail due to network errors or ser
 You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:

 ```ts
-import { configure } from "@trigger.dev/sdk/v3";
+import { configure } from "@trigger.dev/sdk";

 configure({
  requestOptions: {
@@ -49,7 +49,7 @@ configure({
 All SDK functions also take a `requestOptions` parameter as the last argument, which can be used to customize the request options. You can use this to disable retries for a specific request:

 ```ts
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 async function main() {
  const run = await runs.retrieve("run_1234", {
@@ -26,10 +26,10 @@ yarn add @trigger.dev/sdk@latest

 ## Usage

-All `v3` functionality is provided through the `@trigger.dev/sdk/v3` module. You can import the entire module or individual resources as needed.
+All `v3` functionality is provided through the `@trigger.dev/sdk` module. You can import the entire module or individual resources as needed.

 ```ts
-import { configure, runs } from "@trigger.dev/sdk/v3";
+import { configure, runs } from "@trigger.dev/sdk";

 configure({
  // this is the default and if the `TRIGGER_SECRET_KEY` environment variable is set, can omit calling configure
@@ -17,10 +17,10 @@ Before setting up your project, you need to authenticate the CLI with Trigger.de

 ```bash
 # Login to Trigger.dev
-npx trigger.dev@v4-beta login
+npx trigger.dev@latest login

 # Or with a specific API URL (for self-hosted instances)
-npx trigger.dev@v4-beta login --api-url https://your-trigger-instance.com
+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`).
@@ -32,23 +32,23 @@ Install the required packages based on your package manager:
 <CodeGroup>

 ```bash npm
-npm add @trigger.dev/sdk@v4-beta
-npm add --save-dev @trigger.dev/build@v4-beta
+npm add @trigger.dev/sdk@latest
+npm add --save-dev @trigger.dev/build@latest
 ```

 ```bash pnpm
-pnpm add @trigger.dev/sdk@v4-beta
-pnpm add -D @trigger.dev/build@v4-beta
+pnpm add @trigger.dev/sdk@latest
+pnpm add -D @trigger.dev/build@latest
 ```

 ```bash yarn
-yarn add @trigger.dev/sdk@v4-beta
-yarn add -D @trigger.dev/build@v4-beta
+yarn add @trigger.dev/sdk@latest
+yarn add -D @trigger.dev/build@latest
 ```

 ```bash bun
-bun add @trigger.dev/sdk@v4-beta
-bun add -D @trigger.dev/build@v4-beta
+bun add @trigger.dev/sdk@latest
+bun add -D @trigger.dev/build@latest
 ```

 </CodeGroup>
@@ -82,13 +82,13 @@ You can run the Trigger.dev CLI in two ways:

 ```bash
 # npm
-npx trigger.dev@v4-beta dev
+npx trigger.dev@latest dev

 # pnpm
-pnpm dlx trigger.dev@v4-beta dev
+pnpm dlx trigger.dev@latest dev

 # yarn
-yarn dlx trigger.dev@v4-beta dev
+yarn dlx trigger.dev@latest dev
 ```

 ### Option 2: Add as dev dependency
@@ -98,7 +98,7 @@ Add the CLI to your `package.json`:
 ```json
 {
  "devDependencies": {
-    "trigger.dev": "4.0.0-v4-beta.26"
+    "trigger.dev": "^4.0.0"
  }
 }
 ```
@@ -120,11 +120,11 @@ Make sure to pin the version of the CLI to the same version as the SDK that you

 ```json
 "devDependencies": {
-  "trigger.dev": "4.0.0-v4-beta.26",
-  "@trigger.dev/build": "4.0.0-v4-beta.26"
+  "trigger.dev": "^4.0.0",
+  "@trigger.dev/build": "^4.0.0"
 },
 "dependencies": {
-  "@trigger.dev/sdk": "4.0.0-v4-beta.26"
+  "@trigger.dev/sdk": "^4.0.0"
 }
 ```

@@ -239,16 +239,16 @@ If you're building a React frontend application and want to display task status

 ```bash
 # npm
-npm install @trigger.dev/react-hooks@v4-beta
+npm install @trigger.dev/react-hooks@latest

 # pnpm
-pnpm add @trigger.dev/react-hooks@v4-beta
+pnpm add @trigger.dev/react-hooks@latest

 # yarn
-yarn add @trigger.dev/react-hooks@v4-beta
+yarn add @trigger.dev/react-hooks@latest

 # bun
-bun add @trigger.dev/react-hooks@v4-beta
+bun add @trigger.dev/react-hooks@latest
 ```

 ### Basic usage
@@ -396,10 +396,10 @@ packages:
  "name": "@repo/tasks",
  "version": "0.0.0",
  "dependencies": {
-    "@trigger.dev/sdk": "4.0.0-v4-beta.26"
+    "@trigger.dev/sdk": "^4.0.0"
  },
  "devDependencies": {
-    "@trigger.dev/build": "4.0.0-v4-beta.26"
+    "@trigger.dev/build": "^4.0.0"
  },
  "exports": {
    ".": "./src/trigger/index.ts",
@@ -509,7 +509,7 @@ Run the development server for the tasks package:
 ```bash
 # From the root of your monorepo
 cd packages/tasks
-npx trigger.dev@v4-beta dev
+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
@@ -527,13 +527,13 @@ This approach installs Trigger.dev directly in individual apps that need backgro
 {
  "name": "web",
  "dependencies": {
-    "@trigger.dev/sdk": "4.0.0-v4-beta.26",
+    "@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-v4-beta.26"
+    "@trigger.dev/build": "^4.0.0"
  }
 }
 ```
@@ -612,7 +612,7 @@ export async function triggerHelloWorld(name: string) {
 ```bash
 # From the app directory
 cd apps/web
-npx trigger.dev@v4-beta dev
+npx trigger.dev@latest dev

 # Or from the root using turbo
 turbo run dev:trigger --filter=web
@@ -0,0 +1,305 @@
+---
+title: "Migrating from v3"
+description: "What's new in v4, how to migrate, and breaking changes."
+---
+
+import NodeVersions from "/snippets/node-versions.mdx";
+import MigrateV4UsingAi from "/snippets/migrate-v4-using-ai.mdx";
+
+## What's new in v4?
+
+| Feature                                                              | Description                                                                                                                                                                                                |
+| :------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Wait for token](/wait-for-token)                                    | Create and wait for tokens to be completed, enabling approval workflows and waiting for arbitrary external conditions.                                                                                     |
+| Wait idempotency                                                     | Skip waits if the same idempotency key is used again when using [wait for](/wait-for#wait-idempotency), [wait until](/wait-until#wait-idempotency), or [wait for token](/wait-for-token#wait-idempotency). |
+| [Priority](/runs/priority)                                           | Specify a priority when triggering a task.                                                                                                                                                                 |
+| [Global lifecycle hooks](/tasks/overview#global-lifecycle-hooks)     | Register global lifecycle hooks that are executed for all runs, regardless of the task.                                                                                                                    |
+| [onWait and onResume](/tasks/overview#onwait-and-onresume-functions) | Run code when a run is paused or resumed because of a wait.                                                                                                                                                |
+| [onComplete](/tasks/overview#oncomplete-function)                    | Run code when a run completes, regardless of whether it succeeded or failed.                                                                                                                               |
+| [onCancel](/tasks/overview#oncancel-function)                        | Run code when a run is cancelled.                                                                                                                                                                          |
+| [Hidden tasks](/hidden-tasks)                                        | Create tasks that are not exported from your trigger files but can still be executed.                                                                                                                      |
+| [Middleware & locals](#middleware-and-locals)                        | The middleware system runs at the top level, executing before and after all lifecycle hooks. The locals API allows sharing data between middleware and hooks.                                              |
+| [useWaitToken](/realtime/react-hooks/use-wait-token)                 | Use the useWaitToken hook to complete a wait token from a React component.                                                                                                                                 |
+| [ai.tool](/tasks/schemaTask#ai-tool)                                 | Create an AI tool from an existing `schemaTask` to use with the Vercel [AI SDK](https://vercel.com/docs/ai-sdk).                                                                                           |
+
+## Node.js support
+
+<NodeVersions />
+
+## How to migrate to v4
+
+First read the deprecations and breaking changes sections below.
+
+We recommend the following steps to migrate to v4:
+
+1. Install the v4 package.
+2. Run the `trigger dev` CLI command and test your tasks locally, fixing any breaking changes.
+3. Deploy to the staging environment and test your tasks in staging, fixing any breaking changes. (this step is optional, but highly recommended)
+4. Once you've verified that v4 is working as expected, you should deploy your application backend with the updated v4 package.
+5. Once you've deployed your application backend, you should deploy your tasks to the production environment.
+
+Note that between steps 4 and 5, runs triggered with the v4 package will continue using v3, and only new runs triggered after step 5 is complete will use v4.
+
+<Warning>
+  Once v4 is activated in your environment, there will be a period of time where old runs will
+  continue to execute using v3, while new runs will use v4. Because these engines use completely
+  different underlying queues and concurrency models, it's possible you may have up to double the
+  amount of concurrently executing runs. Once the runs drain from the old run engine, the
+  concurrency will return to normal.
+</Warning>
+
+## Migrate using AI
+
+Use the prompt in the accordion below to help you migrate your v3 tasks to v4. The prompt gives good results when using Claude 4 Sonnet. You’ll need a relatively large token limit.
+
+<MigrateV4UsingAi />
+
+## Installation
+
+To opt-in to using v4, you will need to update your dependencies to the latest version:
+
+<CodeGroup>
+
+```bash npx
+npx trigger.dev@latest update
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest update
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest update
+```
+
+</CodeGroup>
+
+This command should update all of your `@trigger.dev/*` packages to a `4.x` version.
+
+## Deprecations
+
+We've deprecated the following APIs:
+
+### @trigger.dev/sdk/v3
+
+We've deprecated the `@trigger.dev/sdk/v3` import path and moved to a new path:
+
+```ts
+// This still works, but will be removed in a future version
+import { task } from "@trigger.dev/sdk/v3";
+
+// This is the new path
+import { task } from "@trigger.dev/sdk";
+```
+
+### `handleError` and `init`
+
+We've renamed the `handleError` hook to `catchError` to better reflect that it can catch and react to errors. `handleError` will be removed in a future version.
+
+`init` was previously used to initialize data used in the run function:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+const myTask = task({
+  init: async () => {
+    return {
+      myClient: new MyClient(),
+    };
+  },
+  run: async (payload: any, { ctx, init }) => {
+    const client = init.myClient;
+    await client.doSomething();
+  },
+});
+```
+
+This has now been deprecated in favor of the `locals` API and middleware. See the [Improved middleware and locals](/tasks/overview#middleware-and-locals-functions) section for more details.
+
+### toolTask
+
+We've deprecated the `toolTask` function, which created both a Trigger.dev task and a tool compatible with the Vercel [AI SDK](https://vercel.com/docs/ai-sdk):
+
+```ts
+import { toolTask, schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+import { generateText } from "ai";
+
+const myToolTask = toolTask({
+  id: "my-tool-task",
+  run: async (payload: any, { ctx }) => {},
+});
+
+export const myAiTask = schemaTask({
+  id: "my-ai-task",
+  schema: z.object({
+    text: z.string(),
+  }),
+  run: async (payload, { ctx }) => {
+    const { text } = await generateText({
+      prompt: payload.text,
+      model: openai("gpt-4o"),
+      tools: {
+        myToolTask,
+      },
+    });
+  },
+});
+```
+
+We've replaced the `toolTask` function with the `ai.tool` function, which creates an AI tool from an existing `schemaTask`. See the [ai.tool](/tasks/schemaTask#ai-tool) page for more details.
+
+## Breaking changes
+
+### Queue changes
+
+Previously, it was possible to specify a queue name of a queue that did not exist, along with a concurrency limit. The queue would then be created "on-demand" with the specified concurrency limit. If the queue did exist, the concurrency limit of the queue would be updated to the specified value:
+
+```ts
+await myTask.trigger({ foo: "bar" }, { queue: { name: "my-queue", concurrencyLimit: 10 } });
+```
+
+This is no longer possible, and queues must now be defined ahead of time using the `queue` function:
+
+```ts
+import { queue } from "@trigger.dev/sdk";
+
+const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 10,
+});
+```
+
+Now when you trigger a task, you can only specify the queue by name:
+
+```ts
+await myTask.trigger({ foo: "bar" }, { queue: "my-queue" });
+```
+
+Or you can set the queue on the task:
+
+```ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const myQueue = queue({
+  name: "my-queue",
+  concurrencyLimit: 10,
+});
+
+export const myTask = task({
+  id: "my-task",
+  queue: myQueue,
+  run: async (payload: any, { ctx }) => {},
+});
+
+// You can optionally specify the queue directly on the task
+export const myTask2 = task({
+  id: "my-task-2",
+  queue: {
+    name: "my-queue-2",
+    concurrencyLimit: 50,
+  },
+  run: async (payload: any, { ctx }) => {},
+});
+```
+
+Now you can trigger these tasks without having to specify the queue name in the trigger options:
+
+```ts
+await myTask.trigger({ foo: "bar" }); // Will use the queue defined on the task
+await myTask2.trigger({ foo: "bar" }); // Will use the queue defined on the task
+```
+
+### Lifecycle hooks
+
+We've changed the function signatures of the lifecycle hooks to be more consistent and easier to use, by unifying all the parameters into a single object that can be destructured.
+
+Previously, hooks received a payload as the first argument and then an additional object as the second argument:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: (payload, { ctx }) => {},
+  run: async (payload, { ctx }) => {},
+});
+```
+
+Now, all the parameters are passed in a single object:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: ({ payload, ctx }) => {},
+  // The run function still uses separate parameters
+  run: async (payload, { ctx }) => {},
+});
+```
+
+This is true for all the lifecycle hooks:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  onStart: ({ payload, ctx, task }) => {},
+  onSuccess: ({ payload, ctx, task, output }) => {},
+  onFailure: ({ payload, ctx, task, error }) => {},
+  onWait: ({ payload, ctx, task, wait }) => {},
+  onResume: ({ payload, ctx, task, wait }) => {},
+  onComplete: ({ payload, ctx, task, result }) => {},
+  catchError: ({ payload, ctx, task, error, retry, retryAt, retryDelayInMs }) => {},
+  run: async (payload, { ctx }) => {},
+});
+```
+
+### Context changes
+
+We've made a few small changes to the `ctx` object:
+
+- `ctx.attempt.id` and `ctx.attempt.status` have been removed. `ctx.attempt.number` is still available.
+- `ctx.task.exportName` has been removed (since we no longer require tasks to be exported to be triggered).
+
+### BatchTrigger changes
+
+The `batchTrigger` function no longer returns a `runs` list directly. In v3, you could access the runs directly from the batch handle:
+
+```ts
+// In v3
+const batchHandle = await tasks.batchTrigger([
+  [myTask, { foo: "bar" }],
+  [myOtherTask, { baz: "qux" }],
+]);
+
+// You could access runs directly
+console.log(batchHandle.runs);
+```
+
+In v4, you now need to use the `runs.list()` method to get the list of runs:
+
+```ts
+// In v4
+const batchHandle = await tasks.batchTrigger([
+  [myTask, { foo: "bar" }],
+  [myOtherTask, { baz: "qux" }],
+]);
+
+// Now you need to call runs.list()
+const runs = await batchHandle.runs.list();
+console.log(runs);
+```
+
+### OpenTelemetry
+
+We are now using newer versions of the OpenTelemetry packages. This means that if you're using custom exporters you may need to update the packages:
+
+| Package                                   | Previous Version | New Version | Change Type  |
+| ----------------------------------------- | ---------------- | ----------- | ------------ |
+| `@opentelemetry/api-logs`                 | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/exporter-logs-otlp-http`  | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/exporter-trace-otlp-http` | 0.52.1           | 0.203.0     | Major update |
+| `@opentelemetry/instrumentation`          | 0.52.1           | 0.203.0     | Major update |
@@ -204,7 +204,7 @@ In Trigger.dev it looks like this:

 ```ts /trigger/someTasks.ts
 import { performLongRunningTask } from "@/utils/performLongRunningTask";
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 //named export
 export const longRunningTask = task({
@@ -259,7 +259,7 @@ export default defer.cron(sendMondayNewletter, "0 0 * * 1");
 In Trigger.dev the task looks like this:

 ```ts
-import { schedules } from "@trigger.dev/sdk/v3";
+import { schedules } from "@trigger.dev/sdk";

 //this task will run when any of the attached schedules trigger
 export const sendMondayNewletter = schedules.task({
@@ -48,7 +48,7 @@ This is typically called by Mergent via HTTP POST, and you’d register the endp
 #### The same task in Trigger.dev

 ```ts trigger/processVideo.ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";

 export const processVideoTask = task({
  id: "process-video",
@@ -83,7 +83,7 @@ export async function dailyReportTask(req) {
 **Trigger.dev scheduled task:**

 ```ts trigger/dailyReport.ts
-import { schedules } from "@trigger.dev/sdk/v3";
+import { schedules } from "@trigger.dev/sdk";

 export const dailyReportTask = schedules.task({
  id: "daily-report",
@@ -1,14 +1,12 @@
 ---
 title: "Docker (legacy)"
-description: "You can self-host Trigger.dev on your own infrastructure using Docker."
+description: "Self-host Trigger.dev on your own infrastructure using Docker."
 ---

-<Tip>This guide is for v3, you can find the v4 guide [here](/self-hosting/docker).</Tip>
+<Note>This is a legacy guide for self-hosting v3 using Docker, you can find the v4 guide [here](/self-hosting/docker).</Note>

 <Warning>Security, scaling, and reliability concerns are not fully addressed here. This guide is meant for evaluation purposes and won't result in a production-ready deployment.</Warning>

-<Note>This guide is for Docker only. We don't currently provide documentation for Kubernetes.</Note>
-
 ## Overview

 <Frame>
@@ -14,9 +14,10 @@ It's important to note that only actively executing runs count towards concurren
 By default, all tasks have an unbounded concurrency limit, limited only by the overall concurrency limits of your environment. This means that each task could possibly "fill up" the entire
 concurrency limit of your environment.

+Each individual queue has a maximum concurrency limit equal to your environment's base concurrency limit. If you don't explicitly set a queue's concurrency limit, it will default to your environment's base concurrency limit.
+
 <Note>
-  Your environment has a maximum concurrency limit which depends on your plan. If you're a paying
-  customer you can request a higher limit by [contacting us](https://www.trigger.dev/contact).
+  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 limits by [contacting us](https://www.trigger.dev/contact).
 </Note>

 ## Setting task concurrency
@@ -182,12 +183,21 @@ export const subtask = task({

 ## Waits and concurrency

-With our [task checkpoint system](/how-it-works#the-checkpoint-resume-system), a parent task can trigger and wait for a subtask to complete. The way this system interacts with the concurrency system is a little complicated but important to understand. There are two main scenarios that we handle slightly differently:
+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.

- When a parent task waits for a subtask on a different queue.
- When a parent task waits for a subtask on the same queue.
+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.

-These scenarios are discussed in more detail below:
+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

 <Note>
  We sometimes refer to the parent task as the "parent" and the subtask as the "child". Subtask and
@@ -196,7 +206,7 @@ These scenarios are discussed in more detail below:

 ### Waiting for a subtask on a different queue

-During the time when a parent task is waiting on a subtask, the "concurrency" slot of the parent task is still considered occupied on the parent task queue, but is temporarily "released" to the environment. An example will help illustrate this:
+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({
@@ -205,8 +215,10 @@ export const parentTask = task({
    concurrencyLimit: 1,
  },
  run: async (payload) => {
-    //trigger a subtask
+    //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
  },
 });

@@ -218,17 +230,11 @@ export const subtask = task({
 });
 ```

-For example purposes, let's say the environment concurrency limit is 1. When the parent task is triggered, it will occupy the only slot in the environment. When the parent task triggers the subtask, the subtask will be placed in the queue for the subtask. The parent task will then wait for the subtask to complete. During this time, the parent task slot is temporarily released to the environment, allowing another task to run. Once the subtask completes, the parent task slot is reoccupied.
-
-This system prevents "stuck" tasks. If the parent task were to wait on the subtask and not release the slot, the environment would be stuck with only one task running.
-
-And because only the environment slot is released, the parent task queue slot is still occupied. This means that if another task is triggered on the parent task queue, it will be placed in the queue and wait for the parent task to complete, respecting the concurrency limit.
+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.

 ### Waiting for a subtask on the same queue

-Because tasks can trigger and wait recursively, or share the same queue, we've added special handling for when a parent task waits for a subtask on the same queue.
-
-Recall above that when waiting for a subtask on a different queue, the parent task slot is temporarily released to the environment. When the parent task and the subtask share a queue, we also release the parent task slot to the queue. Again, an example will help illustrate this:
+When a parent task and subtask share the same queue, the checkpointing behavior ensures that recursive task execution can proceed without deadlocks, up to the queue's concurrency limit.

 ```ts /trigger/waiting-same-queue.ts
 export const myQueue = queue({
@@ -240,7 +246,7 @@ export const parentTask = task({
  id: "parent-task",
  queue: myQueue,
  run: async (payload) => {
-    //trigger a subtask
+    //trigger a subtask and wait for it to complete
    await subtask.triggerAndWait(payload);
  },
 });
@@ -254,9 +260,9 @@ export const subtask = task({
 });
 ```

-In this example, the parent task and the subtask share the same queue with a concurrency limit of 1. When the parent task triggers the subtask, the parent task slot is released to the queue, giving the subtask the opportunity to run. Once the subtask completes, the parent task slot is reoccupied.
+When the parent task checkpoints at the `triggerAndWait` call, it releases its concurrency slot back to the queue, allowing the subtask to execute. Once the subtask completes, the parent task will resume.

-It's very important to note that we only release at-most X slots to the queue, where X is the concurrency limit of the queue. This means that you can only trigger and wait for X subtasks on the same queue. If you try to trigger and wait for more than X subtasks, you will receive a `RECURSIVE_WAIT_DEADLOCK` error. The following example will result in a deadlock:
+However, you can only have recursive waits up to your queue's concurrency limit. If you exceed this limit, you will receive a `RECURSIVE_WAIT_DEADLOCK` error:

 ```ts /trigger/deadlock.ts
 export const myQueue = queue({
@@ -268,7 +274,6 @@ export const parentTask = task({
  id: "parent-task",
  queue: myQueue,
  run: async (payload) => {
-    //trigger a subtask
    await subtask.triggerAndWait(payload);
  },
 });
@@ -277,8 +282,7 @@ export const subtask = task({
  id: "subtask",
  queue: myQueue,
  run: async (payload) => {
-    //trigger a subtask
-    await subsubtask.triggerAndWait(payload);
+    await subsubtask.triggerAndWait(payload); // This will cause a deadlock
  },
 });

@@ -291,12 +295,16 @@ export const subsubtask = task({
 });
 ```

-Now this will result in a `RECURSIVE_WAIT_DEADLOCK` error because the parent task is waiting for the subtask, and the subtask is waiting for the subsubtask, but there is no more concurrency available in the queue. It will look a bit like this in the logs:
+This results in a `RECURSIVE_WAIT_DEADLOCK` error because the queue can only support one level of recursive waiting with a concurrency limit of 1:

 ![Recursive task deadlock](/images/recursive-task-deadlock-min.png)

 ### Mitigating recursive wait deadlocks

-If you are recursively triggering and waiting for tasks on the same queue, you can mitigate the risk of a deadlock by increasing the concurrency limit of the queue. This will allow you to trigger and wait for more subtasks.
+To avoid recursive wait deadlocks when using shared queues:

-You can also use different queues for the parent task and the subtask. This will allow you to trigger and wait for more subtasks without the risk of a deadlock.
+1. **Increase the queue's concurrency limit** to allow more levels of recursive waiting
+2. **Use different queues** for parent and child tasks to eliminate the possibility of deadlock
+3. **Design task hierarchies** to minimize deep recursive waiting patterns
+
+Remember that the number of recursive waits you can have on a shared queue is limited by that queue's concurrency limit.
@@ -0,0 +1,34 @@
+---
+title: useWaitToken
+description: Use the useWaitToken hook to complete a wait token from a React component
+---
+
+We've added a new `useWaitToken` react hook that allows you to complete a wait token from a React component, using a Public Access Token.
+
+```ts backend.ts
+import { wait } from "@trigger.dev/sdk";
+
+// Somewhere in your code, you'll need to create the token and then pass the token ID and the public token to the frontend
+const token = await wait.createToken({
+  timeout: "10m",
+});
+
+return {
+  tokenId: token.id,
+  publicToken: token.publicAccessToken, // An automatically generated public access token that expires in 1 hour
+};
+```
+
+Now you can use the `useWaitToken` hook in your frontend code:
+
+```tsx frontend.tsx
+import { useWaitToken } from "@trigger.dev/react-hooks";
+
+export function MyComponent({ publicToken, tokenId }: { publicToken: string; tokenId: string }) {
+  const { complete } = useWaitToken(tokenId, {
+    accessToken: publicToken,
+  });
+
+  return <button onClick={() => complete({ foo: "bar" })}>Complete</button>;
+}
+```
@@ -3,24 +3,18 @@ title: "Run tests"
 description: "You can use the dashboard to run a test of your tasks."
 ---

-From the "Test" page in the sidebar of the dashboard you can run a test for any of your tasks, that includes for any environment.
+From the "Test" page in the side menu of the dashboard you can run a test for any of your tasks from any environment.

-<Steps>
+![Select an environment](/images/test-dashboard.png)

-<Step title="Select an environment">
-  ![Select an environment](/images/test-select-environment.png)
-</Step>
+<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Select a task to test

-<Step title="Select the task to test">
-  ![Select the task to test](/images/test-select-task.png)
-</Step>
+<Icon icon="circle-2" iconType="solid" color="#FF2D6B" size="20" /> Include a payload or metadata

-<Step title="Enter a payload">
-  Select a recent payload as a starting point or enter from scratch. Payloads must be valid JSON – you will see helpful errors if it is not. Press the "Run test" button or use the keyboard shortcut to run the test.
-![Enter a payload](/images/test-set-payload.png)
+<Icon icon="circle-3" iconType="solid" color="#FF2D6B" size="20" /> Configure any additional options like the machine size, queue or delay

-</Step>
+<Icon icon="circle-4" iconType="solid" color="#FF2D6B" size="20" /> Select from previous test runs

-<Step title="View the run live">![View the run live](/images/run-in-progress.png)</Step>
+<Icon icon="circle-5" iconType="solid" color="#FF2D6B" size="20" /> Save the current test configuration as a template for later

-</Steps>
+<Icon icon="circle-6" iconType="solid" color="#FF2D6B" size="20" /> Run the test
@@ -63,7 +63,7 @@ export const heavyTask = task({
 You can use [runs.retrieve()](/management/runs/retrieve) to get a single run or [runs.list()](/management/runs/list) to get a list of runs. The response will include `costInCents` `baseCostInCents` and `durationMs` fields.

 ```ts single run
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 const run = await runs.retrieve("run-id");
 console.log(run.costInCents, run.baseCostInCents, run.durationMs);
@@ -71,7 +71,7 @@ const totalCost = run.costInCents + run.baseCostInCents;
 ```

 ```ts multiple runs
-import { runs } from "@trigger.dev/sdk/v3";
+import { runs } from "@trigger.dev/sdk";

 let totalCost = 0;
 for await (const run of runs.list({ tag: "user_123456" })) {
--- a/Show More
+++ b/Show More