feat(build): Add NeonDB branch resolution for Vercel preview environments

.changeset/funny-planes-remember.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/build": patch
+---
+
+syncVercelEnvVars to skip API and read env vars directly from env.process for Vercel build environments. New syncNeonEnvVars build extension for syncing environment variablesfrom Neon database projects to Trigger.dev. The extension automatically detects branches and builds appropriate PostgreSQL connection strings for non-production, non-dev environments (staging, preview).

docs/config/extensions/syncEnvVars.mdx

@@ -80,6 +80,25 @@ The `syncVercelEnvVars` build extension syncs environment variables from your Ve
   the project with the environment variables you want to sync.
 </Note>
 
+<Note>
+  When running the build from a Vercel build environment (e.g., during a Vercel deployment), the
+  environment variable values will be read from `process.env` instead of fetching them from the
+  Vercel API. This is determined by checking if the `VERCEL` environment variable is present. The
+  API is still used to determine which environment variables are configured for your project, but
+  the actual values come from the local environment. Reading values from `process.env` allows the
+  extension to use values that Vercel integrations (such as the Neon integration) set per preview
+  deployment in the "Provisioning Integrations" phase that happens just before the Vercel build
+  starts.
+</Note>
+
+<Note>
+  If you have the Neon database Vercel integration installed and are running builds outside of the
+  Vercel environment, we recommend using `syncNeonEnvVars` in addition to `syncVercelEnvVars` for your
+  database environment variables. This ensures that the correct database connection strings are used for your 
+  selected environment and current branch, as `syncVercelEnvVars` may not accurately reflect
+  branch-specific database credentials when run locally.
+</Note>
+
 ```ts
 import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
@@ -114,3 +133,79 @@ export default defineConfig({
   },
 });
 ```
+
+### syncNeonEnvVars
+
+The `syncNeonEnvVars` build extension syncs environment variables from your Neon database project to Trigger.dev. It automatically detects branches and builds the appropriate database connection strings for your environment.
+
+<Note>
+  You need to set the `NEON_ACCESS_TOKEN` and `NEON_PROJECT_ID` environment variables, or pass them
+  as arguments to the `syncNeonEnvVars` build extension. You can generate a `NEON_ACCESS_TOKEN` in
+  your Neon [dashboard](https://console.neon.tech/app/settings/api-keys).
+</Note>
+
+<Note>
+  When running the build from a Vercel environment (determined by checking if the `VERCEL`
+  environment variable is present), this extension is skipped entirely. This is because Neon's
+  Vercel integration already handles environment variable synchronization in Vercel environments.
+</Note>
+
+<Note>
+  If you have the Neon database Vercel integration installed and are running builds outside of the
+  Vercel environment, we recommend using `syncNeonEnvVars` in addition to `syncVercelEnvVars` for your
+  database environment variables. This ensures that the correct database connection strings are used for your 
+  selected environment and current branch, as `syncVercelEnvVars` may not accurately reflect
+  branch-specific database credentials when run locally.
+</Note>
+
+<Note>
+  This extension is skipped for `prod` environments. It is designed to sync branch-specific
+  database connections for preview/staging environments.
+</Note>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncNeonEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    // This will automatically use the NEON_ACCESS_TOKEN and NEON_PROJECT_ID environment variables
+    extensions: [syncNeonEnvVars()],
+  },
+});
+```
+
+Or you can pass in the token and project ID as arguments:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncNeonEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      syncNeonEnvVars({
+        projectId: "your-neon-project-id",
+        neonAccessToken: "your-neon-access-token",
+        branch: "your-branch-name", // optional, defaults to ctx.branch
+        databaseName: "your-database-name", // optional, defaults to the first database
+        roleName: "your-role-name", // optional, defaults to the database owner
+        envVarPrefix: "MY_PREFIX_", // optional, prefix for all synced env vars
+      }),
+    ],
+  },
+});
+```
+
+The extension syncs the following environment variables (with optional prefix):
+
+- `DATABASE_URL` - Pooled connection string
+- `DATABASE_URL_UNPOOLED` - Direct connection string
+- `POSTGRES_URL`, `POSTGRES_URL_NO_SSL`, `POSTGRES_URL_NON_POOLING`
+- `POSTGRES_PRISMA_URL` - Connection string optimized for Prisma
+- `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE`
+- `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`

docs/guides/examples/vercel-sync-env-vars.mdx

@@ -19,6 +19,14 @@ To sync environment variables, you just need to add our build extension to your
   the project with the environment variables you want to sync.
 </Note>
 
+<Note>
+  When running the build from a Vercel build environment (e.g., during a Vercel deployment), the
+  environment variable values will be read from `process.env` instead of fetching them from the
+  Vercel API. This is determined by checking if the `VERCEL` environment variable is present. The
+  API is still used to determine which environment variables are configured for your project, but
+  the actual values come from the local environment.
+</Note>
+
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";
 import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";

packages/build/src/extensions/core.ts

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