Environment variables

Environment variables provide configuration to builds and Functions without committing values to source control.

Environment scopes

Easel separates Preview and Production values. A deployment receives values from the environment used to build it.

Changing a variable does not mutate an existing immutable deployment. Create a new deployment for the change to take effect.

Build-time variables

Build tools and frameworks can read variables while compiling the application.

const apiOrigin = process.env.API_ORIGIN;

Public prefixes such as NEXT_PUBLIC_, VITE_, and framework equivalents can embed values into browser JavaScript. Never place secrets in public variables.

Runtime variables

Server-side routes and Functions can read environment variables at runtime through the framework's normal API.

const databaseUrl = process.env.DATABASE_URL;

Treat all secret values as sensitive even when they are only available server-side.

Variable names and values

Use descriptive uppercase names. Avoid storing large files or structured credentials when a dedicated secret mechanism is required.

Combined environment variable names and values are subject to the Function environment size limit. See Function limits.

Local development

Keep local values in the framework's supported local environment files and exclude secret-bearing files from Git. Easel does not automatically synchronize local files with project settings unless a documented CLI command provides that behavior.

Rotation

To rotate a credential:

1. Create the replacement credential at the provider.
2. Update Preview and validate a new Preview deployment.
3. Update Production and create a Production deployment.
4. Promote the new deployment.
5. Revoke the previous credential after rollback risk has passed.

Troubleshooting

When a value is missing or stale, verify:

• The correct Easel project
• Preview versus Production scope
• Exact variable name and capitalization
• Whether the variable is required during build or runtime
• Whether a new deployment was created after the change
• Whether the framework embeds public variables at build time