Add a better explanation and details about env vars

Author: matt-aitken

docs/deployment/preview-branches.mdx

@@ -7,9 +7,13 @@ import UpgradeToV4Note from "/snippets/upgrade-to-v4-note.mdx";
 
 <UpgradeToV4Note />
 
-## How does it work?
+## How to use preview branches
 
-The Preview environment is special – you create branches from it. We recommend you automatically create a preview branch for each git branch when a Pull Request is opened and then archive it automatically when the PR is merged/closed.
+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.
+
+![Preview environment and branches](/deployment/preview-environment-branches.png)
+
+We recommend you automatically create a preview branch for each git branch when a Pull Request is opened and then archive it automatically when the PR is merged/closed.
 
 The process to use preview branches looks like this:
 
@@ -25,7 +29,7 @@ There are two main ways to do this:
 
 ### Limits on active preview branches
 
-We restrict the number of active preview branches (per project). You can archive a preview branch at any time (automatically or manually) to unlock another slot.
+We restrict the number of active preview branches (per project). You can archive a preview branch at any time (automatically or manually) to unlock another slot – or you can upgrade your plan.
 
 Once archived you can still view the dashboard for the branch but you can't trigger or execute runs (or other write operations).
 
@@ -145,3 +149,55 @@ From the "Preview branches" page you can create a branch:
 You can also archive a branch:
 
 ![Archive preview branch](/deployment/preview-branches-archive.png)
+
+## Environment variables
+
+You can set environment variables for "Preview" and they will get applied to all branches (existing and new). You can also set environment variables for a specific branch. If they are set for both then the branch-specific variables will take precedence.
+
+![Environment variables](/deployment/preview-environment-variables.png)
+
+These can be set manually in the dashboard, or automatically at deploy time using the [syncEnvVars()](/config/extensions/syncEnvVars) or [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) build extensions.
+
+### Sync environment variables
+
+You can find this in the Trigger.dev dashboard. Full instructions are in the [syncEnvVars()](/config/extensions/syncEnvVars) documentation.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  //... other config
+  build: {
+    // This will automatically detect and sync environment variables
+    extensions: [
+      syncEnvVars(async (ctx) => {
+        // You can fetch env variables from a 3rd party service like Infisical, Hashicorp Vault, etc.
+        // The ctx.branch will be set if it's a preview deployment.
+        return await fetchEnvVars(ctx.environment, ctx.branch);
+      }),
+    ],
+  },
+});
+```
+
+### Sync Vercel environment variables
+
+You need to set the `VERCEL_ACCESS_TOKEN`, `VERCEL_PROJECT_ID` and `VERCEL_TEAM_ID` environment variables. You can find these in the Vercel dashboard. Full instructions are in the [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) documentation.
+
+The extension will automatically detect a preview branch deploy from Vercel and sync the appropriate environment variables.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  //... other config
+  build: {
+    // This will automatically detect and sync environment variables
+    extensions: [syncVercelEnvVars()],
+  },
+});
+```