Webiny Docs home page
WHAT YOU'LL LEARN
- How to use environment variables in Webiny - Application-specific variable prefixes - Best practices for sensitive data

Overview
anchor

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
anchor

Webiny uses prefixes to route variables to specific applications:

  • WEBINY_ADMIN_ - Variables for the Admin application
  • WEBINY_API_ - Variables for the API application

Usage
anchor

Setting Variables
anchor

Create a .env file in your project root:

.env
# Admin application variables
WEBINY_ADMIN_ANALYTICS_ID=UA-123456789
WEBINY_ADMIN_CUSTOM_API_URL=https://api.example.com
WEBINY_ADMIN_FEATURE_FLAGS=dark-mode,beta-features

# API application variables
WEBINY_API_SMTP_HOST=smtp.sendgrid.net
WEBINY_API_SMTP_USER=apikey
WEBINY_API_SMTP_PASS=SG.xxxxx
WEBINY_API_EXTERNAL_SERVICE_KEY=sk_live_xxxxx

Accessing Variables
anchor

In your extensions, access variables through process.env:

extensions/MyApiExtension.ts
// API extension - only WEBINY_API_ variables available
const smtpConfig = {
  host: process.env.WEBINY_API_SMTP_HOST,
  user: process.env.WEBINY_API_SMTP_USER,
  pass: process.env.WEBINY_API_SMTP_PASS
};

// This would be undefined in API:
console.log(process.env.WEBINY_ADMIN_ANALYTICS_ID); // undefined
extensions/MyAdminExtension.tsx
// Admin extension - only WEBINY_ADMIN_ variables available
const analyticsId = process.env.WEBINY_ADMIN_ANALYTICS_ID;

// This would be undefined in Admin:
console.log(process.env.WEBINY_API_SMTP_HOST); // undefined

TypeScript Support
anchor

Add type definitions for your environment variables:

webiny-env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    // Admin variables
    WEBINY_ADMIN_ANALYTICS_ID?: string;
    WEBINY_ADMIN_CUSTOM_API_URL?: string;
    WEBINY_ADMIN_FEATURE_FLAGS?: string;

    // API variables
    WEBINY_API_SMTP_HOST?: string;
    WEBINY_API_SMTP_USER?: string;
    WEBINY_API_SMTP_PASS?: string;
    WEBINY_API_EXTERNAL_SERVICE_KEY?: string;
  }
}

Best Practices
anchor

Security
anchor

  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
anchor

Create .env.example for team reference:

.env.example
# Analytics Configuration (required)
WEBINY_ADMIN_ANALYTICS_ID=

# Email Service (optional)
WEBINY_API_SMTP_HOST=
WEBINY_API_SMTP_USER=
WEBINY_API_SMTP_PASS=

# External API (required for payments)
WEBINY_API_EXTERNAL_SERVICE_KEY=

Variable Naming
anchor

Follow consistent naming conventions:

# Good - clear, prefixed, uppercase
WEBINY_API_STRIPE_SECRET_KEY=sk_live_xxx
WEBINY_ADMIN_GOOGLE_MAPS_API_KEY=xxx

# Bad - unclear, no prefix, mixed case
stripeKey=sk_live_xxx
Google_Maps_Key=xxx