Navigation

Environment Variables

Environment variables in Forge allow you to configure your applications with different settings for different environments (Production, Staging, Development) without hardcoding sensitive information or environment-specific values in your code.

Overview

Forge supports environment variables through multiple mechanisms depending on your deployment method and application type. Understanding these differences is crucial for proper configuration and successful deployments.

Note: Environment variables are managed through your site's settings in the Forge dashboard and are persisted across deployments.

Accessing Environment Variables

To configure environment variables for your site:

  1. Navigate to your site in the Forge Dashboard
  2. Go to the site's settings
  3. Look for the "Environment Variables" section
  4. Add, edit, or remove environment variables as needed

Deployment Methods

1. GitHub Auto-Sync Deployment

Forge automatically pulls code from your GitHub repository and processes environment variables during deployment.

How it works:

  • Environment variables are processed by the EnvironmentVariablesParser
  • Supports <!-- @env VARIABLE_NAME --> placeholders in HTML/JS files
  • Real-time environment variable injection during deployment

Example Usage:

<!-- In your HTML files -->
<script>
  const apiUrl = '<!-- @env VUE_APP_API_URL -->';
  const apiKey = '<!-- @env VUE_APP_API_KEY -->';
</script>
Pros:
  • Automatic deployments on code changes
  • Centralized environment variable management
  • Real-time environment variable injection
Cons:
  • Limited to @env placeholder format
  • Doesn't support process.env in compiled applications

2. Hammer Cloud Compilation Service

Forge sends build requests to Hammer Manager, which passes environment variables to the cloud compilation service.

How it works:

  • Build service runs yarn build or similar with environment variables injected
  • Supports process.env variables during build process
  • Handles modern build tools and frameworks

Example Usage:

// In your source code (Vue.js, React, etc.)
const apiUrl = process.env.VUE_APP_API_URL;
const apiKey = process.env.VUE_APP_API_KEY;
Pros:
  • Supports modern build tools and frameworks
  • Handles process.env variables natively
  • Automated build process
Cons:
  • Requires Hammer Manager integration
  • Build time can be longer
  • More complex setup

3. Drag-and-Drop Deployment

You upload pre-built application files (e.g., dist folder) and Forge processes them for environment variables.

How it works:

  • Files are processed by EnvironmentVariablesParser for @env placeholders
  • No build process occurs on Forge servers
  • Only supports <!-- @env VARIABLE_NAME --> placeholders
Important: Drag-and-drop deployment does NOT support process.env variables. You must build locally with environment variables before uploading.
Pros:
  • Fast deployment
  • Full control over build process
  • Works with any static site
Cons:
  • Requires local build with environment variables
  • Limited to @env placeholder format
  • Manual process

Use Cases

Static HTML/JS Sites

Recommended Method: GitHub Auto-Sync or Drag-and-Drop

Implementation:

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <script>
    const config = {
      apiUrl: '<!-- @env API_URL -->',
      apiKey: '<!-- @env API_KEY -->'
    };
    
    // Use config.apiUrl and config.apiKey in your application
  </script>
</body>
</html>

Vue.js Applications

Recommended Method: Hammer Cloud Compilation or Local Build + Drag-and-Drop

Option A: Hammer Cloud Compilation

// In your Vue.js source code
const apiUrl = process.env.VUE_APP_API_URL;
const apiKey = process.env.VUE_APP_API_KEY;

// These will be replaced during the build process

Option B: Local Build + Drag-and-Drop

  1. Create .env.production file locally: 
    VUE_APP_API_URL=https://api.example.com
VUE_APP_API_KEY=your-api-key
  2. Build locally: 
    yarn build --mode production
  3. Upload the dist folder to Forge

React Applications

Recommended Method: Hammer Cloud Compilation or Local Build + Drag-and-Drop

Implementation:

// In your React source code
const apiUrl = process.env.REACT_APP_API_URL;
const apiKey = process.env.REACT_APP_API_KEY;

Troubleshooting

Environment Variables Not Replacing

Symptoms: <!-- @env VARIABLE_NAME --> placeholders remain in deployed files

Solutions:

  • Verify environment variables are set in Forge admin dashboard
  • Check that variable names match exactly (case-sensitive)
  • Ensure you're using the correct placeholder format

process.env Variables Not Working

Symptoms: process.env references remain in compiled output

Solutions:

  • For drag-and-drop: Build locally with environment variables before uploading
  • For Hammer compilation: Verify environment variables are passed to build service
  • Check that environment variables are prefixed correctly (e.g., VUE_APP_, REACT_APP_)

Environment Variables Missing in Production

Symptoms: Application works locally but not in production

Solutions:

  • Verify environment variables are configured in Forge admin
  • Check deployment method compatibility
  • Review build process and environment variable injection

Best Practices

1. Environment Variable Naming

  • Use descriptive, uppercase names
  • Prefix with framework-specific prefixes when required:
    • Vue.js: VUE_APP_
    • React: REACT_APP_
    • Next.js: NEXT_PUBLIC_

2. Security

  • Never commit sensitive environment variables to version control
  • Use Forge's environment variable management for production secrets
  • Rotate sensitive keys regularly

3. Development Workflow

  • Use .env.local for local development
  • Use .env.production for production builds
  • Document required environment variables in README

4. Deployment Strategy

  • Choose deployment method based on your application type
  • Test environment variable processing before production deployment
  • Have a fallback strategy for environment variable injection

Examples

Example 1: Vue.js with Hammer Compilation

Source Code:

// src/config.js
export const config = {
  apiUrl: process.env.VUE_APP_API_URL,
  apiKey: process.env.VUE_APP_API_KEY,
  environment: process.env.VUE_APP_ENVIRONMENT || 'development'
};

Forge Environment Variables:

{
  "VUE_APP_API_URL": "https://api.example.com",
  "VUE_APP_API_KEY": "your-api-key",
  "VUE_APP_ENVIRONMENT": "production"
}

Example 2: Static Site with @env Placeholders

HTML File:

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="app"></div>
  <script>
    window.APP_CONFIG = {
      apiUrl: '<!-- @env API_URL -->',
      apiKey: '<!-- @env API_KEY -->',
      environment: '<!-- @env ENVIRONMENT|development -->'
    };
  </script>
</body>
</html>

Forge Environment Variables:

{
  "API_URL": "https://api.example.com",
  "API_KEY": "your-api-key",
  "ENVIRONMENT": "production"
}

Example 3: Local Build for Drag-and-Drop

Local .env.production:

VUE_APP_API_URL=https://api.example.com
VUE_APP_API_KEY=your-api-key
VUE_APP_ENVIRONMENT=production

Build Command:

yarn build --mode production

Upload:

Zip the dist folder and upload to Forge

Debugging Steps

  1. Check Environment Variables in Forge:
    • Go to Forge admin dashboard
    • Navigate to your site's environment variables
    • Verify all required variables are set
  2. Check Compiled Output:
    • For drag-and-drop deployments, examine the uploaded files
    • Look for remaining process.env or @env references
  3. Check Build Logs:
    • For Hammer compilation, review build logs for environment variable processing
    • Look for any errors or warnings
  4. Test Locally:
    • Build your application locally with production environment variables
    • Verify environment variables are properly replaced
Conclusion: Understanding how environment variables work in Forge is essential for successful deployments. Choose the right deployment method for your application type and ensure proper environment variable configuration. When in doubt, test locally first and verify the compiled output before deploying to production.
Environments Overview
Javascript Bundlers

Join the Discussion

Have questions or want to share your experience? Join our community discussion to connect with other developers and get help from the Forge team.

Visit Forum Discussion