@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/vercel-integration.mdx

@@ -0,0 +1,250 @@
+---
+title: "Vercel integration"
+description: "Automatically deploy your tasks whenever you deploy to Vercel."
+---
+
+## How it works
+
+The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev, and sets up [version skew protection](/deployment/atomic-deployment) so your app and tasks stay in sync.
+
+This eliminates the need to manually run the `trigger.dev deploy` command or maintain custom CI/CD workflows for Vercel-based projects.
+
+<Note>
+  The Vercel integration requires the [GitHub integration](/github-integration) to be connected as
+  well, since Trigger.dev builds your tasks from your GitHub repository.
+</Note>
+
+## Installation
+
+You can connect Vercel from two entry points:
+
+### From the Trigger.dev dashboard
+
+<Steps>
+
+<Step title="Connect Vercel">
+  Go to your project's **Settings** page and click **Connect Vercel**. This will redirect you to
+  Vercel to authorize the Trigger.dev app.
+</Step>
+
+<Step title="Select a Vercel project">
+  Choose which Vercel project to connect to your Trigger.dev project.
+</Step>
+
+<Step title="Map environments">
+  If your Vercel project has custom environments, choose which one maps to your Trigger.dev staging
+  environment.
+</Step>
+
+<Step title="Sync environment variables">
+  Review the environment variables that will be pulled from Vercel into Trigger.dev. You can
+  deselect any variables you don't want to sync.
+</Step>
+
+<Step title="Configure build options">
+  Optionally adjust [build options](#build-options) for env var pulling and new env var discovery.
+</Step>
+
+<Step title="Connect GitHub">
+  If your GitHub repository isn't already connected, you'll be prompted to connect it.
+</Step>
+
+</Steps>
+
+### From the Vercel Marketplace
+
+<Steps>
+
+<Step title="Install the integration">
+  Install the [Trigger.dev integration from the Vercel
+  Marketplace](https://vercel.com/marketplace/trigger). This will redirect you to Trigger.dev to
+  complete setup.
+</Step>
+
+<Step title="Select your Trigger.dev organization and project">
+  Choose which Trigger.dev organization and project to connect. If you're new to Trigger.dev, you'll
+  be guided through creating an organization and project.
+</Step>
+
+<Step title="Connect GitHub">
+  If your GitHub repository isn't already connected, you'll be prompted to connect it.
+</Step>
+
+</Steps>
+
+<Note>
+  When installing from the Vercel Marketplace, default Build options are applied automatically. You
+  can adjust them later in your project settings.
+</Note>
+
+<Warning>
+  **Vercel Root Directory:** If your Vercel project uses a **Root Directory** (e.g. you deploy a
+  single subfolder such as `app` or `web`), you may see "The specified Root Directory does not
+  exist" after connecting the integration. If you see this error, try using the **repository root**
+  (leave Root Directory empty) in your Vercel project settings. If your Vercel frontend build
+  requires a Root Directory (e.g. in a monorepo), keep that setting in Vercel and instead point
+  Trigger.dev to the subfolder by setting the **Trigger config file** path (and other [Build
+  options](#build-options)) in your Trigger.dev project configuration. Trigger.dev always builds
+  from the repo root.
+</Warning>
+
+## Environment variable sync
+
+The integration syncs environment variables in both directions:
+
+**Vercel → Trigger.dev**: Environment variables from your Vercel project are pulled into Trigger.dev. This happens during the initial setup and optionally before each build. Variables are synced per-environment (production, staging, preview).
+
+**Trigger.dev → Vercel**: Trigger.dev syncs API keys (like `TRIGGER_SECRET_KEY`) to your Vercel project so your app can communicate with Trigger.dev.
+
+The following variables are excluded from the Vercel → Trigger.dev sync:
+
+- `TRIGGER_SECRET_KEY`, `TRIGGER_API_URL`, `TRIGGER_VERSION`, `TRIGGER_PREVIEW_BRANCH`, `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` (managed by Trigger.dev)
+- Sensitive/secret-type variables (Vercel API limitation)
+
+You can control sync behavior per-variable from your project's Vercel settings. Deselecting a variable prevents its value from being updated during future syncs.
+
+<Note>
+  Environment variables are pulled from Vercel before each build. To sync updated values into
+  Trigger.dev, trigger a new Vercel deployment — either by pushing a commit to your connected branch
+  or by redeploying from the Vercel dashboard.
+</Note>
+
+<Warning>
+  If you are experiencing incorrectly populated environment variables, check that you are not using
+  the `syncVercelEnvVars` build extension in your `trigger.config.ts`. This extension is deprecated
+  and conflicts with the Vercel integration's built-in env var syncing. Remove it if present.
+</Warning>
+
+### Supabase and Neon database branching
+
+If you use [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) or [Neon Database Branching](https://neon.tech/docs/guides/branching-intro) for preview environments, disable syncing for database env vars on the Environment Variables page and use the [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncsupabaseenvvars) or [syncNeonEnvVars](/config/extensions/syncEnvVars#syncneonenvvars) build extensions instead. These extensions automatically resolve the correct branch-specific credentials at build time.
+
+## Version skew protection
+
+Your Vercel app and your tasks are deployed separately, so there is always a window where a new app can trigger tasks built from older code. [Version skew protection](/deployment/atomic-deployment) closes that window: each Trigger.dev deployment is tagged with your commit SHA, your app sends the same SHA when it triggers, and every run is pinned to the deployment built from the same commit. Runs triggered before the task build finishes wait for it rather than running on the previous version.
+
+The integration sets this up for you:
+
+- It sets `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1` on your Vercel project when you connect it, and re-asserts it on every build — so existing projects pick it up on their next deployment.
+- It passes your commit SHA as the deployment's external id.
+- `VERCEL_GIT_COMMIT_SHA` is available at runtime on Vercel, so the SDK finds the matching id with no work from you.
+
+There is nothing to enable, and it works in production, staging and preview alike.
+
+### Production waits for your tasks
+
+A production deployment from a push to the branch Trigger.dev builds for production gets a blocking **Trigger.dev Build** check. Vercel holds the deployment until the task build for the same commit finishes, then assigns your production domains as usual. If the task build fails or is canceled, the check fails and the Vercel deployment doesn't go live, so your app never ships against tasks that didn't build.
+
+If no task build for the commit has started within 10 minutes, the check fails too.
+
+To retry after a failed build, re-run the **Trigger.dev deployment** check on the commit in GitHub. Once that build succeeds, redeploy from Vercel or push a new commit.
+
+A production deployment with no task build to wait for is never held: its check is marked skipped. That covers deployments from the Vercel CLI, from a branch that isn't your production branch in Trigger.dev, and from projects without a connected GitHub repository. Preview and staging deployments aren't held either: their check passes straight away, and version skew protection makes their runs wait for the matching task build instead.
+
+<Note>
+  Version skew protection requires the `@trigger.dev/sdk` release that introduces external
+  deployment ids. Check the [release
+  notes](https://github.com/triggerdotdev/trigger.dev/releases) for the exact version, or just use
+  the latest. On an older SDK no id is sent and your runs execute on the current version, with no
+  warning.
+</Note>
+
+To opt out, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Vercel project. The integration only writes the variable when it is absent, so a value you set is never overwritten.
+
+## Atomic deployments
+
+<Warning>
+  **Automatic atomic deployments are deprecated.** Use [version skew
+  protection](/deployment/atomic-deployment) instead — it needs no second Vercel deployment,
+  doesn't touch `Auto-assign Custom Production Domains`, and covers staging and preview as well as
+  production. Production deployments still wait for your task build through the blocking check.
+
+  Nothing is being switched off. The setting stays in your project's Vercel settings, keeps working,
+  and remains the way to hold your Vercel deployment back until your tasks have built. New
+  connections have it off by default.
+</Warning>
+
+Atomic deployments ensure your Vercel app and Trigger.dev tasks are deployed in sync. When enabled, Trigger.dev gates your Vercel deployment until the task build completes, then triggers a Vercel redeployment with the correct `TRIGGER_VERSION` set. This guarantees your app always uses the matching version of your tasks.
+
+```mermaid
+sequenceDiagram
+  participant Dev as Developer
+  participant GH as GitHub
+  participant V as Vercel
+  participant TD as Trigger.dev
+
+  Dev->>GH: Push code
+  GH->>V: Webhook: new commit
+  V->>V: Start deployment
+  V->>TD: Deployment created
+  Dev->>GH: Create pull request
+  GH->>TD: Pull request created
+  TD->>TD: Start task build
+
+  V->>TD: Deployment check
+  TD-->>V: Check pending (gate deployment)
+  TD->>TD: Build completes
+  TD->>V: Set TRIGGER_VERSION env var
+  TD->>V: Trigger redeployment
+  V->>V: Redeploy with correct TRIGGER_VERSION
+  V->>TD: Deployment check (redeployment)
+  TD-->>V: Check passed
+  V->>V: Promote deployment
+  V->>TD: Deployment promoted
+  TD->>TD: Promote build
+```
+
+Atomic deployments are off by default for new connections. Projects that already had them enabled keep them enabled until you turn them off. Enabling them asks you to confirm first.
+
+<Note>
+  When atomic deployments are enabled, the integration automatically disables `Auto-assign Custom
+  Production Domains` on your Vercel project. This is required so that Vercel doesn't promote a
+  deployment before the Trigger.dev build is ready. If you turn atomic deployments off, re-enable
+  that setting in Vercel or promote deployments yourself.
+</Note>
+
+Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For how to move off them, see [legacy atomic deployments](/deployment/atomic-deployment#legacy-atomic-deployments).
+
+## Environment mapping
+
+The integration maps Vercel environments to Trigger.dev environments:
+
+| Vercel environment | Trigger.dev environment        |
+| ------------------ | ------------------------------ |
+| Production         | Production                     |
+| Custom environment | Staging (you choose which one) |
+| Preview            | Preview                        |
+| Development        | Development                    |
+
+If your Vercel project has a custom environment, you can select which one maps to your Trigger.dev staging environment during setup or in your project settings.
+
+<Note>
+  Preview deployments require the preview environment to be enabled on your project. Learn more
+  about [preview branches](/deployment/preview-branches).
+</Note>
+
+## Build options
+
+You can configure the following settings per-environment from your project's Vercel settings:
+
+- **Atomic deployments** (deprecated): Controls whether Trigger.dev gates and redeploys your Vercel deployment to keep it in sync. Off by default for new connections — use [version skew protection](/deployment/atomic-deployment) instead.
+- **Pull env vars before build**: When enabled, Trigger.dev pulls the latest environment variables from Vercel before each build. Enabled for production, staging, and preview by default.
+- **Discover new env vars**: When enabled, new environment variables found in Vercel that don't yet exist in Trigger.dev are created automatically during builds. Only available for environments that also have env var pulling enabled. Enabled for production, staging, and preview by default.
+
+To change build options that would normally go in `trigger.config.ts` (such as [extensions](/config/config-file#extensions) or other build configuration), use **Build options** on your project's configuration page in the Trigger.dev dashboard.
+
+## Disconnecting
+
+You can disconnect the Vercel integration from either side:
+
+- **From Trigger.dev**: Go to your project **Settings** and disconnect Vercel.
+- **From Vercel**: Uninstall the Trigger.dev integration from your Vercel dashboard. This is automatically detected and the connection is removed on the Trigger.dev side.
+
+Disconnecting stops automatic deployments, environment variable syncing, and deployment checks. Your existing deployments and environment variables are not affected.
+
+## Related
+
+- [Atomic deployments (version skew protection)](/deployment/atomic-deployment)
+- [GitHub integration](/github-integration)
+- [Environment variables](/deploy-environment-variables)
+- [Preview branches](/deployment/preview-branches)

package/docs/versioning.mdx

@@ -0,0 +1,58 @@
+---
+title: "Versioning"
+description: "We use atomic versioning to ensure that started tasks are not affected by changes to the task code."
+---
+
+A version is a bundle of tasks at a certain point in time.
+
+## Version identifiers
+
+Version identifiers look like this:
+
+- `20240313.1` - March 13th, 2024, version 1
+- `20240313.2` - March 13th, 2024, version 2
+- `20240314.1` - March 14th, 2024, version 1
+
+You can see there are two parts to the version identifier:
+
+- The date (in reverse format)
+- The version number
+
+Versions numbers are incremented each time a new version is created for that date and environment. So it's possible to have `20240313.1` in both the `dev` and `prod` environments.
+
+## Version locking
+
+When a task run starts it is locked to the latest version of the code (for that environment). Once locked it won't change versions, even if you deploy new versions. This is to ensure that a task run is not affected by changes to the code.
+
+Delayed runs are locked to the version that's active when they begin executing, not when they're enqueued.
+
+### Child tasks and version locking
+
+Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
+
+| Trigger function        | Parent task version | Child task version | isLocked |
+| ----------------------- | ------------------- | ------------------ | -------- |
+| `trigger()`             | `20240313.2`        | Latest             | No       |
+| `batchTrigger()`        | `20240313.2`        | Latest             | No       |
+| `triggerAndWait()`      | `20240313.2`        | `20240313.2`       | Yes      |
+| `batchTriggerAndWait()` | `20240313.2`        | `20240313.2`       | Yes      |
+
+## Local development
+
+When running the local server (using `npx trigger.dev dev`), every relevant code change automatically creates a new version of all tasks.
+
+So a task run will continue running on the version it was locked to. We do this by spawning a new process for each task run. This ensures that the task run is not affected by changes to the code.
+
+## Deployment
+
+Every deployment creates a new version of all tasks for that environment.
+
+Because your application and your tasks deploy separately, a release of your app can briefly trigger tasks that belong to a different version. [Version skew protection](/deployment/atomic-deployment) pins each run to the deployment built from the same commit, once your app sends the id it was deployed with.
+
+## Retries and reattempts
+
+When a task has an uncaught error it will [retry](/errors-retrying), if the task has retries configured (the `retry` option or `retries.default` in your config). Retries are locked to the original version of the run.
+
+## Replays
+
+A "replay" is a new run of a task that uses the same inputs but will use the latest version of the code. This is useful when you fix a bug and want to re-run a task with the same inputs. See [replaying](/replaying) for more information.

package/docs/video-walkthrough.mdx

@@ -0,0 +1,23 @@
+---
+title: "Video walkthrough"
+description: "Go from zero to a working task in your Next.js app in 10 minutes."
+---
+
+{" "}
+<iframe
+  width="100%"
+  height="315"
+  src="https://www.youtube.com/embed/YH_4c0K7fGM?si=5JzZmZseuqI5aciM"
+  title="Trigger.dev walkthrough"
+  allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  referrerPolicy="strict-origin-when-cross-origin"
+  allowFullScreen
+/>
+
+### In this video we cover the following topics:
+
+- [0:00](https://youtu.be/YH_4c0K7fGM?si=J8svVzotZtyTXDap&t=0) – [Install Trigger.dev](/quick-start) in an existing Next.js project
+- [1:44](https://youtu.be/YH_4c0K7fGM?si=J8svVzotZtyTXDap&t=104) – [Run and test](/run-tests) the "Hello, world!" example project
+- [2:09](https://youtu.be/YH_4c0K7fGM?si=FMTP8ep_cDBCU0_x&t=128) – Create and run an AI image generation task that uses [Fal.ai](https://fal.ai) – ([View the code](/guides/examples/fal-ai-image-to-cartoon))
+- [6:25](https://youtu.be/YH_4c0K7fGM?si=pPc8iLI2Y9FGD3yo&t=385) – Create and run a [Realtime](/realtime/overview) example using [React hooks](/realtime/react-hooks) – ([View the code](/guides/examples/fal-ai-realtime))
+- [11:10](https://youtu.be/YH_4c0K7fGM?si=Mjd0EvvNsNlVouvY&t=670) – [Deploy your task](/cli-deploy-commands) to the Trigger.dev Cloud