Environment Variables

Overview

Environment variables in Webiny are optional for most scenarios. When needed, they follow a prefix-based system that ensures variables are only available to the appropriate application. This prevents accidental exposure of sensitive data between applications.

Application Prefixes

Webiny uses prefixes to route variables to specific applications:

• WEBINY_ADMIN_ - Variables for the Admin application
• WEBINY_API_ - Variables for the API application
• No prefix - Available to all applications (use sparingly)

Usage

Setting Variables

Create a .env file in your project root:

Accessing Variables

In your extensions, access variables through process.env:

TypeScript Support

Add type definitions for your environment variables:

Environment-Specific Variables

Local Development

Variables in .env are loaded during:

• yarn webiny watch admin
• yarn webiny watch api
• yarn webiny deploy

Deployed Environments

For deployed environments, set variables before deployment:

CI/CD Integration

In CI/CD pipelines, set environment variables:

Best Practices

Security

1. Never commit .env - Add to .gitignore
2. Use prefixes - Isolate sensitive data by application
3. Rotate secrets - Change production secrets regularly
4. Minimal exposure - Only set variables that are needed

Documentation

Create .env.example for team reference:

Variable Naming

Follow consistent naming conventions:

Common Use Cases

Third-Party Services

Feature Flags

API Configuration

Debugging

Verify Variables

Check loaded variables during development:

Common Issues

Variable not available:

• Check prefix matches application (ADMIN vs API)
• Ensure .env file is in project root
• Restart watch command after changing .env
• Verify no typos in variable names

Variables in wrong application:

• Admin extensions can’t access WEBINY_API_ variables
• API extensions can’t access WEBINY_ADMIN_ variables
• Use correct prefix for the target application

Infrastructure Variables

For infrastructure extensions, access variables directly:

Migration From V5

If upgrading from Webiny v5:

1. Add prefixes to existing variables
2. Update code to use prefixed names
3. Test thoroughly in development