feat(webapp,cli): support empty-string environment variable values

Adds support for environment variables with empty-string values, rolling
out gradually. Once enabled for your organization, an empty value stays
stored and available to tasks, including through environment-variable
imports and Vercel sync. Deleting a variable remains a separate action.
Also fixes local dev environment precedence so freshly resolved project
values reach task processes correctly.

Mono-RevId: 25dea78a2c72a984a9bd9ac432c11026f220576c

Author: d-cs

.changeset/empty-dev-env-vars.md

@@ -0,0 +1,6 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+Fix stale and empty project environment values in `trigger dev`, and support empty values in `syncEnvVars()`.

.server-changes/envvar-empty-value.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Support empty-string environment values across the dashboard, API, and Vercel sync behind a feature flag, disabled by default.

apps/webapp/app/models/vercelIntegration.server.ts

@@ -1,3 +1,11 @@
+import { emptyEnvironmentVariableValuesEnabledForProject } from "~/v3/environmentVariables/emptyValuesFlag.server";
+import {
+  normalizeTarget,
+  isVercelSecretType,
+  toVercelEnvironmentVariableValue,
+  resolveVercelSharedValue,
+  mergeVercelEnvironmentVariableValues,
+} from "~/v3/vercel/environmentVariableValues";
 import pLimit from "p-limit";
 import { Vercel } from "@vercel/sdk";
 import type {
@@ -38,12 +46,6 @@ import {
 // Pure helpers
 // ---------------------------------------------------------------------------
 
-function normalizeTarget(target: string[] | string | undefined): string[] {
-  if (Array.isArray(target)) return target.filter(Boolean);
-  if (typeof target === "string") return [target];
-  return [];
-}
-
 function readProjectEnvs(
   response: unknown,
   logContext: Record<string, unknown>
@@ -86,10 +88,6 @@ function hasVercelEnvVarForTarget(envs: ResponseBodyEnvs[], key: string, target:
   });
 }
 
-function isVercelSecretType(type: string): boolean {
-  return type === "secret" || type === "sensitive";
-}
-
 export type CreateEnvVarsIfAbsentResult = {
   written: string[];
   skipped: string[];
@@ -226,19 +224,6 @@ function toVercelCustomEnvironment({
   return { id, slug, description, branchMatcher };
 }
 
-function toVercelEnvironmentVariableValue(
-  env: ResponseBodyEnvs
-): VercelEnvironmentVariableValue | null {
-  if (!env.value) return null;
-  return {
-    key: env.key,
-    value: env.value,
-    target: normalizeTarget(env.target),
-    type: env.type,
-    isSecret: isVercelSecretType(env.type),
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Repository
 // ---------------------------------------------------------------------------
@@ -474,7 +459,8 @@ export class VercelIntegrationRepository {
     teamId?: string | null,
     target?: string,
     /** If provided, only include keys that pass this filter */
-    shouldIncludeKey?: (key: string) => boolean
+    shouldIncludeKey?: (key: string) => boolean,
+    allowEmptyValues = true
   ): ResultAsync<VercelEnvironmentVariableValue[], VercelApiError> {
     return wrapVercelCallWithRecovery(
       client.projects.filterProjectEnvs({
@@ -499,7 +485,9 @@ export class VercelIntegrationRepository {
       return ResultAsync.fromPromise(
         Promise.all(
           filteredEnvs.map((env) =>
-            concurrencyLimit(() => this.#resolveEnvVarValue(client, projectId, teamId, env))
+            concurrencyLimit(() =>
+              this.#resolveEnvVarValue(client, projectId, teamId, env, allowEmptyValues)
+            )
           )
         ),
         (error) => toVercelApiError(error)
@@ -511,12 +499,13 @@ export class VercelIntegrationRepository {
     client: Vercel,
     projectId: string,
     teamId: string | null | undefined,
-    env: ResponseBodyEnvs
+    env: ResponseBodyEnvs,
+    allowEmptyValues: boolean
   ): Promise<VercelEnvironmentVariableValue | null> {
     // Non-encrypted vars: use value from list response if present
     if (env.type !== "encrypted" || !env.id) {
       if (env.value === undefined || env.value === null) return null;
-      return toVercelEnvironmentVariableValue(env);
+      return toVercelEnvironmentVariableValue(env, allowEmptyValues);
     }
 
     // Encrypted vars: fetch decrypted value via individual endpoint
@@ -545,7 +534,8 @@ export class VercelIntegrationRepository {
 
     // API returns union: ResponseBody1 has no value, ResponseBody2/3 have value
     const decryptedValue = (result.value as { value?: string }).value;
-    if (typeof decryptedValue !== "string") return null;
+    if (typeof decryptedValue !== "string" || (!allowEmptyValues && decryptedValue.trim() === ""))
+      return null;
 
     return {
       key: env.key,
@@ -653,7 +643,8 @@ export class VercelIntegrationRepository {
     client: Vercel,
     accessToken: string,
     teamId: string,
-    projectId?: string // Optional: filter by project
+    projectId?: string,
+    allowEmptyValues = true
   ): ResultAsync<
     Array<{
       key: string;
@@ -684,53 +675,43 @@ export class VercelIntegrationRepository {
 
               if (isSecret) return null;
 
-              const listValue = env.value;
-              const applyToAllCustomEnvs = env.applyToAllCustomEnvironments;
-
-              if (listValue) {
-                return {
-                  key: envKey,
-                  value: listValue,
-                  target: normalizeTarget(env.target),
-                  type,
-                  isSecret,
-                  applyToAllCustomEnvironments: applyToAllCustomEnvs,
-                };
-              }
-
-              // Try to get the decrypted value for this shared env var
-              const getResult = await callVercelWithRecovery(
-                client.environment.getSharedEnvVar({
-                  id: envId,
-                  teamId,
-                }),
-                VercelSchemas.getSharedEnvVar,
-                { context: "getSharedEnvVar" }
-              );
+              const value = await resolveVercelSharedValue(
+                env.value,
+                async () => {
+                  const getResult = await callVercelWithRecovery(
+                    client.environment.getSharedEnvVar({ id: envId, teamId }),
+                    VercelSchemas.getSharedEnvVar,
+                    { context: "getSharedEnvVar" }
+                  );
 
-              if (getResult.isOk()) {
-                if (!getResult.value.value) return null;
-                return {
-                  key: envKey,
-                  value: getResult.value.value,
-                  target: normalizeTarget(env.target),
-                  type,
-                  isSecret,
-                  applyToAllCustomEnvironments: applyToAllCustomEnvs,
-                };
-              }
-
-              logger.warn("Failed to get decrypted value for shared env var", {
-                teamId,
-                projectId,
-                envId,
-                envKey,
-                error: getResult.error.message,
-                errorType: getResult.error.errorType,
-                status: getResult.error.status,
-                authInvalid: getResult.error.authInvalid,
-              });
-              return null;
+                  if (getResult.isOk()) {
+                    return getResult.value.value ?? null;
+                  }
+
+                  logger.warn("Failed to get decrypted value for shared env var", {
+                    teamId,
+                    projectId,
+                    envId,
+                    envKey,
+                    error: getResult.error.message,
+                    errorType: getResult.error.errorType,
+                    status: getResult.error.status,
+                    authInvalid: getResult.error.authInvalid,
+                  });
+                  return null;
+                },
+                allowEmptyValues
+              );
+              if (value === null) return null;
+
+              return {
+                key: envKey,
+                value,
+                target: normalizeTarget(env.target),
+                type,
+                isSecret,
+                applyToAllCustomEnvironments: env.applyToAllCustomEnvironments,
+              };
             })
           )
         ),
@@ -1334,6 +1315,9 @@ export class VercelIntegrationRepository {
           }
 
           const envVarRepository = new EnvironmentVariablesRepository();
+          const allowEmptyValues = await emptyEnvironmentVariableValuesEnabledForProject(
+            params.projectId
+          );
 
           // Fetch shared env vars once (they apply across all targets)
           let sharedEnvVars: Array<{
@@ -1350,7 +1334,8 @@ export class VercelIntegrationRepository {
               client,
               accessToken,
               params.teamId,
-              params.vercelProjectId
+              params.vercelProjectId,
+              allowEmptyValues
             );
             sharedEnvVars = sharedResult.unwrapOr([]);
           }
@@ -1373,7 +1358,8 @@ export class VercelIntegrationRepository {
                   params.vercelProjectId,
                   params.teamId,
                   mapping.vercelTarget,
-                  shouldIncludeKey
+                  shouldIncludeKey,
+                  allowEmptyValues
                 );
 
                 if (envVarsResult.isErr()) {
@@ -1399,11 +1385,10 @@ export class VercelIntegrationRepository {
                   return matchesTarget || matchesCustomEnv;
                 });
 
-                const projectEnvVarKeys = new Set(projectEnvVars.map((v) => v.key));
-                const sharedEnvVarsToAdd = filteredSharedEnvVars.filter(
-                  (v) => !projectEnvVarKeys.has(v.key)
+                const mergedEnvVars = mergeVercelEnvironmentVariableValues(
+                  projectEnvVars,
+                  filteredSharedEnvVars
                 );
-                const mergedEnvVars = [...projectEnvVars, ...sharedEnvVarsToAdd];
 
                 if (mergedEnvVars.length === 0) {
                   return;

apps/webapp/app/presenters/v3/EnvironmentVariablesPresenter.server.ts

@@ -1,3 +1,4 @@
+import { emptyEnvironmentVariableValuesEnabled } from "~/v3/environmentVariables/emptyValuesFlag.server";
 import type { PrismaClient, PrismaReplicaClient } from "~/db.server";
 import { $replica, prisma } from "~/db.server";
 import type { Project } from "~/models/project.server";
@@ -39,6 +40,7 @@ export class EnvironmentVariablesPresenter {
     const project = await this.#replicaClient.project.findFirst({
       select: {
         id: true,
+        organization: { select: { featureFlags: true } },
       },
       where: {
         slug: projectSlug,
@@ -176,6 +178,10 @@ export class EnvironmentVariablesPresenter {
     }
 
     return {
+      allowEmptyEnvironmentVariableValues: await emptyEnvironmentVariableValuesEnabled(
+        project.organization.featureFlags,
+        this.#prismaClient
+      ),
       environmentVariables: environmentVariables.flatMap((environmentVariable) => {
         return sortedEnvironments.flatMap((env) => {
           const valueRecord = environmentVariable.values.find((v) => v.environmentId === env.id);

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables.new/route.tsx

@@ -1,5 +1,9 @@
 import { getFormProps, useForm, type FieldMetadata, type FormMetadata } from "@conform-to/react";
-import { parseWithZod } from "@conform-to/zod/v4";
+import {
+  emptyEnvironmentVariableValuesEnabled,
+  EMPTY_ENV_VALUES_DISABLED,
+} from "~/v3/environmentVariables/emptyValuesFlag.server";
+import { parseEnvironmentVariableForm } from "~/v3/environmentVariables/forms";
 import {
   LockClosedIcon,
   LockOpenIcon,
@@ -54,15 +58,18 @@ import {
   v3EnvironmentVariablesPath,
 } from "~/utils/pathBuilder";
 import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
-import { EnvironmentVariableKey } from "~/v3/environmentVariables/repository";
+import {
+  EnvironmentVariableKey,
+  EnvironmentVariableValue,
+} from "~/v3/environmentVariables/repository";
 import { findUnauthorizedEnvironmentId } from "~/v3/writableEnvironments";
 import { pageMeta } from "~/utils/pageTitle";
 
 export const meta = pageMeta("New environment variable");
 
 const Variable = z.object({
   key: EnvironmentVariableKey,
-  value: z.string().nonempty("Value is required"),
+  value: EnvironmentVariableValue,
 });
 
 type Variable = z.infer<typeof Variable>;
@@ -121,7 +128,7 @@ export const action = dashboardAction(
     }
 
     const formData = await request.formData();
-    const submission = parseWithZod(formData, { schema });
+    const submission = parseEnvironmentVariableForm(formData, schema);
 
     if (submission.status !== "success") {
       return json(submission.reply());
@@ -162,6 +169,7 @@ export const action = dashboardAction(
       },
       select: {
         id: true,
+        organization: { select: { featureFlags: true } },
       },
     });
     if (!project) {
@@ -193,6 +201,13 @@ export const action = dashboardAction(
       );
     }
 
+    if (
+      submission.value.variables.some((v) => v.value.trim() === "") &&
+      !(await emptyEnvironmentVariableValuesEnabled(project.organization.featureFlags))
+    ) {
+      return json(submission.reply({ formErrors: [EMPTY_ENV_VALUES_DISABLED] }));
+    }
+
     const repository = new EnvironmentVariablesRepository(prisma);
     const result = await repository.create(project.id, {
       ...submission.value,
@@ -238,7 +253,8 @@ export default function Page() {
     parentData,
     "Environment variables page loader data must be defined when rendering the create dialog"
   );
-  const { environments, hasStaging, writableEnvironmentIds } = parentData;
+  const { environments, hasStaging, writableEnvironmentIds, allowEmptyEnvironmentVariableValues } =
+    parentData;
   // Creating a variable is a write, so gate the targets on write access.
   const writableEnvironmentIdSet = new Set(writableEnvironmentIds);
   const lastSubmission = useActionData();
@@ -266,7 +282,7 @@ export default function Page() {
     // TODO: type this
     lastResult: lastSubmission as any,
     onValidate({ formData }) {
-      return parseWithZod(formData, { schema });
+      return parseEnvironmentVariableForm(formData, schema, allowEmptyEnvironmentVariableValues);
     },
     shouldRevalidate: "onSubmit",
     defaultValue: {