From 577a4bf4971d5e0ef0e64b845b8ceb64ea244d78 Mon Sep 17 00:00:00 2001 From: Lindsey Stead Date: Thu, 13 Nov 2025 09:49:54 -0800 Subject: [PATCH] docs: improve env var documentation with .env upload + ctx environment details --- docs/deploy-environment-variables.mdx | 127 ++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/docs/deploy-environment-variables.mdx b/docs/deploy-environment-variables.mdx index f9e447036f..e123f34170 100644 --- a/docs/deploy-environment-variables.mdx +++ b/docs/deploy-environment-variables.mdx @@ -83,6 +83,84 @@ We have a complete set of SDK functions (and REST API) you can use to directly m | [envvars.update()](/management/envvars/update) | Update a single environment variable | | [envvars.del()](/management/envvars/delete) | Delete a single environment variable | +#### Initial load from .env file + +To initially load environment variables from a `.env` file into your Trigger.dev cloud environment, you can use `envvars.upload()`. This is useful for one-time bulk imports when setting up a new project or environment. + +```ts +import { envvars } from "@trigger.dev/sdk"; +import { readFileSync } from "fs"; +import { parse } from "dotenv"; + +// Read and parse your .env file +const envContent = readFileSync(".env.production", "utf-8"); +const parsed = parse(envContent); + +// Upload to Trigger.dev (replace with your project ref and environment slug) +await envvars.upload("proj_your_project_ref", "prod", { + variables: parsed, + override: false, // Set to true to override existing variables +}); +``` + +When called inside a task, you can omit the project ref and environment slug as they'll be automatically inferred from the task context: + +```ts +import { envvars, task } from "@trigger.dev/sdk"; +import { readFileSync } from "fs"; +import { parse } from "dotenv"; + +export const setupEnvVars = task({ + id: "setup-env-vars", + run: async () => { + const envContent = readFileSync(".env.production", "utf-8"); + const parsed = parse(envContent); + + // projectRef and environment slug are automatically inferred from ctx + await envvars.upload({ + variables: parsed, + override: false, + }); + }, +}); +``` + + +This is different from `syncEnvVars` which automatically syncs variables during every deploy. Use `envvars.upload()` for one-time initial loads, and `syncEnvVars` for ongoing synchronization. + + +#### Getting the current environment + +When using `envvars.retrieve()` inside a task, you can access the current environment information from the task context (`ctx`). The `envvars.retrieve()` function doesn't return the environment, but you can get it from `ctx.environment`: + +```ts +import { envvars, task } from "@trigger.dev/sdk"; + +export const myTask = task({ + id: "my-task", + run: async (payload, { ctx }) => { + // Get the current environment information + const currentEnv = ctx.environment.slug; // e.g., "dev", "prod", "staging" + const envType = ctx.environment.type; // e.g., "DEVELOPMENT", "PRODUCTION", "STAGING", "PREVIEW" + + // Retrieve an environment variable + // When called inside a task, projectRef and slug are automatically inferred + const apiKey = await envvars.retrieve("API_KEY"); + + console.log(`Retrieved API_KEY from environment: ${currentEnv} (${envType})`); + console.log(`Value: ${apiKey.value}`); + }, +}); +``` + +The context object provides: +- `ctx.environment.slug` - The environment slug (e.g., "dev", "prod") +- `ctx.environment.type` - The environment type ("DEVELOPMENT", "PRODUCTION", "STAGING", or "PREVIEW") +- `ctx.environment.id` - The environment ID +- `ctx.project.ref` - The project reference + +For more information about the context object, see the [Context documentation](/context). + ### Sync env vars from another service You could use the SDK functions above but it's much easier to use our `syncEnvVars` build extension in your `trigger.config` file. @@ -234,3 +312,52 @@ You can now use the `client` object to make authenticated requests to Google API + +## Using `.env.production` or dotenvx with Trigger.dev + +Trigger.dev does not automatically load `.env.production` files or dotenvx files during deploys. +To use these files in your Trigger.dev environment: + +### Option 1 — Manually add your environment variables + +1. Open your `.env.production` (or `.env`) file +2. Copy the full contents +3. Go to your Trigger.dev project → **Environment Variables** +4. Click **Add variables** +5. Paste the contents directly into the editor + +Trigger.dev will automatically parse and create each key/value pair. + +This is the simplest way to bring dotenvx or `.env.production` variables into your Trigger.dev environment. + +### Option 2 — Sync variables automatically using `syncEnvVars` + +If you'd prefer an automated flow, you can use the `syncEnvVars` build extension to programmatically load and return your variables: + +```ts +import { defineConfig } from "@trigger.dev/sdk"; +import { syncEnvVars } from "@trigger.dev/build/extensions/core"; +import dotenvx from "@dotenvx/dotenvx"; +import { readFileSync } from "fs"; + +export default defineConfig({ + project: "", + build: { + extensions: [ + syncEnvVars(async () => { + const envContent = readFileSync(".env.production", "utf-8"); + const parsed = dotenvx.parse(envContent); + return parsed ?? {}; + }), + ], + }, +}); +``` + +This will read your .env.production file using dotenvx and sync the variables to Trigger.dev during every deploy. + +**Summary** + +- Trigger.dev does not automatically detect .env.production or dotenvx files +- You can paste them manually into the dashboard +- Or sync them automatically using a build extension \ No newline at end of file