Environment Variables

Environment variables are key-value pairs that are useful for storing values you wouldn't want to put in code or in a table, such as an API key. You can set environment variables in Convex through the dashboard and access them in functions.

For the best experience, declare your environment variables in convex/convex.config.ts to get type-safe access via the generated env object. You can also access any environment variable via process.env.

Setting environment variables

Under Deployment Settings in the Dashboard, you can see a list of environment variables in the current deployment.

You can add up to 256 environment variables, and the total size of all environment variables (names + values) cannot exceed 512KiB. Environment variable names cannot be more than 256 characters long, and they must start with a letter and only contain letters, numbers, and underscores. Environment variable values cannot be larger than 8KiB.

You can modify environment variables using the pencil icon button:

Environment variables can also be viewed and modified from the command line.

npx convex env list
npx convex env get NAME
npx convex env set NAME 'value'
npx convex env set --from-file .env.convex
npx convex env remove NAME

Using environment variables in dev and prod deployments

Since environment variables are set per-deployment, you can use different values for the same key in dev and prod deployments. This can be useful for when you have different external accounts you'd like to use depending on the environment. For example, you might have a dev and prod SendGrid account for sending emails, and your function expects an environment variable called SENDGRID_API_KEY that should work in both environments.

If you expect an environment variable to be always present in a function, you must add it to all your deployments. In this example, you would add an environment variable with the name SENDGRID_API_KEY to your dev and prod deployments, with a different value for dev and prod.

Declaring environment variables

You can declare the environment variables your app expects in convex/convex.config.ts. Declared environment variables give you type-safe access, validation at deploy time, and clear documentation of what your app needs to run. This also helps prevent removing required environment variables or setting them to invalid values from the dashboard or npx convex env [remove|set] ....

convex/convex.config.ts

import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({
  env: {
    GIPHY_KEY: v.string(),
    LOG_LEVEL: v.optional(
      v.union(v.literal("debug"), v.literal("info"), v.literal("error")),
    ),
  },
});

export default app;

The env option maps variable names to validators from convex/values. The supported validators are:

• v.string() — any string value
• v.literal("value") — an exact string value
• v.union(v.literal("a"), v.literal("b")) — one of several exact values
• v.optional(...) — wraps any of the above to mark a variable as optional

After running npx convex dev, Convex generates a typed env object that you import from _generated/server:

convex/myFunction.ts

import { query, env } from "./_generated/server";

export const gifUrl = query({
  args: {},
  handler: async () => {
    // env.GIPHY_KEY is typed as `string`
    // env.LOG_LEVEL is typed as `"debug" | "info" | "error" | undefined`
    return (
      "https://api.giphy.com/v1/gifs/translate?api_key=" +
      env.GIPHY_KEY +
      "&s=cats"
    );
  },
});

The env import works in queries, mutations, actions, and HTTP actions. TypeScript will catch typos and type mismatches at build time rather than at runtime.

You still need to set the actual values in the dashboard or CLI — declaring them in convex.config.ts defines what's expected, not what the values are.

note

Declaring environment variables is optional. If you don't declare them, you can still access all environment variables via process.env as described below, just without any guarantees about what value they contain.

Passing environment variables to components

Components are isolated from the app's environment variables. When a component declares environment variables in its convex.config.ts, you can provide environment variables when installing it:

convex/convex.config.ts

import { defineApp } from "convex/server";
import { v } from "convex/values";
import myComponent from "@example/my-component/convex.config";

const app = defineApp({
  env: {
    LOG_LEVEL: v.union(
      v.literal("debug"),
      v.literal("info"),
      v.literal("error"),
    ),
  },
});

// Pass by reference — the component's LOG_SEVERITY will always
// match this app's LOG_LEVEL - even when it changes between deploys.
app.use(myComponent, { env: { LOG_SEVERITY: app.env.LOG_LEVEL } });

export default app;

You can also populate component environment variables via literal values:

convex/convex.config.ts

// Pass a literal value
app.use(myComponent, { env: { LOG_SEVERITY: "debug" } });

See Authoring Components: Environment Variables for how to declare environment variables in a component.

Accessing environment variables via process.env

You can access environment variables in Convex functions using process.env.KEY. If the variable is set it is a string, otherwise it is undefined. Here is an example of accessing an environment variable with the key GIPHY_KEY:

function giphyUrl(query) {
  return (
    "https://api.giphy.com/v1/gifs/translate?api_key=" +
    process.env.GIPHY_KEY +
    "&s=" +
    encodeURIComponent(query)
  );
}

tip

If you've declared your environment variables in convex.config.ts, prefer using the typed env import from _generated/server instead of process.env for better type safety.

Note that you should not condition your Convex function exports on environment variables. The set of Convex functions that can be called is determined during deployment and is not reevaluated when you change an environment variable. The following code will throw an error at runtime, if the DEBUG environment variable changes between deployment and calling the function.

// THIS WILL NOT WORK!
export const myFunc = process.env.DEBUG ? mutation(...) : internalMutation(...);

Similarly, environment variables used in cron definitions will only be reevaluated on deployment.

System environment variables

The following environment variables are always available in Convex functions:

• CONVEX_CLOUD_URL - Your deployment URL (eg. https://dusty-nightingale-847.convex.cloud) for use with Convex clients.
• CONVEX_SITE_URL - Your deployment site URL (eg. https://dusty-nightingale-847.convex.site) for use with HTTP Actions

Project environment variable defaults

You can set up default environment variable values for a project in Project Settings.

These default values will be used when creating a new deployment, and will have no effect on existing deployments (they are not kept in sync). You can set a different default value for each deployment type.

The Deployment Settings will indicate when a deployment has environment variables that do not match the project defaults.

You can also change the default environment variables from the CLI using npx convex env default.