feat(buildExtensions): syncSupabaseEnvVars build extension

Author: 0ski

apps/webapp/app/components/integrations/VercelOnboardingModal.tsx

@@ -851,6 +851,31 @@ export function VercelOnboardingModal({
                 Later on environment variables can be pulled before each build.
               </Paragraph>
 
+              <Callout variant="info">
+                <p className="text-xs">
+                  Using Supabase Branching or Neon Database Branching? Pull env vars now, then
+                  disable syncing for database env vars on the Environment Variables page and use{" "}
+                  <a
+                    href="https://trigger.dev/docs/config/extensions/syncEnvVars#syncsupabaseenvvars"
+                    className="text-text-bright underline underline-offset-2 transition hover:text-text-link"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    syncSupabaseEnvVars
+                  </a>{" "}
+                  or{" "}
+                  <a
+                    href="https://trigger.dev/docs/config/extensions/syncEnvVars#syncneonenvvars"
+                    className="text-text-bright underline underline-offset-2 transition hover:text-text-link"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    syncNeonEnvVars
+                  </a>{" "}
+                  build extensions instead.
+                </p>
+              </Callout>
+
               <div className="flex gap-4 text-sm">
                 <div className="rounded border bg-charcoal-750 px-3 py-2">
                   <span className="font-medium text-text-bright">{syncableEnvVars.length}</span>

docs/config/extensions/overview.mdx

@@ -57,6 +57,7 @@ Trigger.dev provides a set of built-in extensions that you can use to customize
 | [additionalPackages](/config/extensions/additionalPackages)           | Install additional npm packages in your build image                            |
 | [syncEnvVars](/config/extensions/syncEnvVars)                         | Automatically sync environment variables from external services to Trigger.dev |
 | [syncVercelEnvVars](/config/extensions/syncEnvVars#syncVercelEnvVars) | Automatically sync environment variables from Vercel to Trigger.dev            |
+| [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncSupabaseEnvVars) | Automatically sync environment variables from Supabase to Trigger.dev          |
 | [esbuildPlugin](/config/extensions/esbuildPlugin)                     | Add existing or custom esbuild extensions to customize your build process      |
 | [emitDecoratorMetadata](/config/extensions/emitDecoratorMetadata)     | Enable `emitDecoratorMetadata` in your TypeScript build                        |
 | [audioWaveform](/config/extensions/audioWaveform)                     | Add Audio Waveform to your build image                                         |

docs/config/extensions/syncEnvVars.mdx

@@ -220,3 +220,72 @@ The extension syncs the following environment variables (with optional prefix):
 - `POSTGRES_PRISMA_URL` - Connection string optimized for Prisma
 - `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE`
 - `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`
+
+### syncSupabaseEnvVars
+
+The `syncSupabaseEnvVars` build extension syncs environment variables from your Supabase project to Trigger.dev. It uses [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) to automatically detect branches and build the appropriate database connection strings and API keys for your environment.
+
+<AccordionGroup>
+<Accordion title="Setting up authentication">
+You need to set the `SUPABASE_ACCESS_TOKEN` and `SUPABASE_PROJECT_ID` environment variables, or pass them
+as arguments to the `syncSupabaseEnvVars` build extension.
+
+You can generate a `SUPABASE_ACCESS_TOKEN` in your Supabase [dashboard](https://supabase.com/dashboard/account/tokens).
+</Accordion>
+
+<Accordion title="Running in Vercel environment">
+When running the build from a Vercel environment (determined by checking if the `VERCEL`
+environment variable is present), this extension is skipped entirely.
+</Accordion>
+</AccordionGroup>
+
+<Note>
+  For `prod` and `dev` environments, this extension uses credentials from your default Supabase
+  branch. For `preview` and `staging` environments, it matches the git branch name to a Supabase
+  branch and syncs the corresponding database connection strings and API keys.
+</Note>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncSupabaseEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    // This will automatically use the SUPABASE_ACCESS_TOKEN and SUPABASE_PROJECT_ID environment variables
+    extensions: [syncSupabaseEnvVars()],
+  },
+});
+```
+
+Or you can pass in the token, project ID, and other options as arguments:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncSupabaseEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      syncSupabaseEnvVars({
+        projectId: "your-supabase-project-id",
+        supabaseAccessToken: "your-supabase-access-token", // optional, we recommend to keep it as env variable
+        branch: "your-branch-name", // optional, defaults to ctx.branch
+        envVarPrefix: "MY_PREFIX_", // optional, prefix for all synced env vars
+      }),
+    ],
+  },
+});
+```
+
+The extension syncs the following environment variables (with optional prefix):
+
+- `DATABASE_URL`, `POSTGRES_URL`, `SUPABASE_DB_URL` — PostgreSQL connection strings
+- `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` — Individual connection parameters
+- `SUPABASE_URL` — Supabase API URL
+- `SUPABASE_ANON_KEY` — Anonymous API key
+- `SUPABASE_SERVICE_ROLE_KEY` — Service role API key
+- `SUPABASE_JWT_SECRET` — JWT secret

docs/vercel-integration.mdx

@@ -105,8 +105,12 @@ The following variables are excluded from the Vercel → Trigger.dev sync:
 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.
 
 <Tip>
-  For dynamic environment variables (e.g., from NeonDB branching), use the `syncEnvVars` build
-  extension instead. Learn more about [environment variables](/deploy-environment-variables).
+  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.
 </Tip>
 
 ## Atomic deployments

packages/build/src/extensions/core.ts

@@ -5,3 +5,4 @@ export * from "./core/aptGet.js";
 export * from "./core/ffmpeg.js";
 export * from "./core/neonSyncEnvVars.js";
 export * from "./core/vercelSyncEnvVars.js";
+export * from "./core/syncSupabaseEnvVars.js";