How to load environment variables

Link to section: local-development#Local development

Link to section: using-env-files#Using .env files

The most common way to manage environment variables during development is using .env files:

DATABASE_HOST=localhost
DATABASE_PORT=5432
NODE_ENV=development
API_KEY=your-secret-key
LOG_LEVEL=debug

Link to section: best-practices-for-env-files#Best practices for .env files

1. Document required variables Create a .env.example file to document required variables:

   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   NODE_ENV=development
   API_KEY=your-secret-key-here
   LOG_LEVEL=info

2. Gitignore configuration Add these patterns to your .gitignore:

   .env
   .env.*
   !.env.example

3. Environment-specific files Use different files for different environments:

   • .env.development - Development settings
   • .env.test - Test environment settings
   • .env.production - Production defaults (if needed)

Link to section: loading-environment-variables#Loading environment variables

Link to section: using-dotenv#Using dotenv

The simplest way to load environment variables is using the dotenv package:

import 'dotenv/config';
// or
import * as dotenv from 'dotenv';
dotenv.config();

Link to section: framework-specific-solutions#Framework-specific solutions

Many frameworks have built-in support for environment variables:

Link to section: nextjs#Next.js

• Automatically loads .env* files
• Supports environment-specific files (.env.development, .env.production)
• Next.js Environment Variables Documentation

Link to section: vite#Vite

• Automatically loads .env files
• Supports mode-specific files (.env.development, .env.production)
• Vite Env Variables Documentation

Link to section: express#Express

import express from 'express';
import dotenv from 'dotenv';

dotenv.config();
const app = express();

Link to section: nestjs#Nest.js

import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
  ],
})

Link to section: runtime-arguments#Runtime arguments

You can also supply variables when running your application:

DATABASE_HOST=localhost DATABASE_PORT=5432 npm start

Link to section: production-deployment#Production deployment

Link to section: cloud-platforms#Cloud platforms

Link to section: aws#AWS

• Use AWS Systems Manager Parameter Store for non-sensitive values
• Use AWS Secrets Manager for sensitive values
• Set environment variables in ECS Task Definitions or Lambda configurations

Link to section: google-cloud-platform#Google Cloud Platform

• Use Cloud Secret Manager for sensitive values
• Set environment variables in Cloud Run or App Engine configurations

Link to section: azure#Azure

• Use Azure Key Vault for sensitive values
• Configure App Settings in Azure App Service

Link to section: container-environments#Container environments

Link to section: docker#Docker

ENV NODE_ENV=production

services:
  app:
    environment:
      - NODE_ENV=production
      - DATABASE_HOST=db

Link to section: kubernetes#Kubernetes

spec:
  containers:
    - name: app
      env:
        - name: NODE_ENV
          value: "production"
        - name: DATABASE_HOST
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: database-host

Link to section: traditional-hosting#Traditional hosting

• Set environment variables through the hosting platform's dashboard
• Use deployment scripts to configure environment variables
• Consider using configuration management tools

Link to section: security-best-practices#Security best practices

1. Never commit sensitive values

   • Keep .env files out of version control
   • Use secrets management services in production

2. Use different values per environment

   • Don't share sensitive credentials between environments
   • Use environment-specific configurations

3. Access control

   • Limit access to production environment variables
   • Use role-based access control for secrets management

4. Encryption

   • Encrypt sensitive values at rest
   • Use secure channels for transmitting secrets

Link to section: validation-and-typesafety#Validation and typesafety

ArkEnv helps ensure your environment variables are valid:

import arkenv from 'arkenv';

export const env = arkenv({
  // Required variables with validation
  DATABASE_HOST: "string.host",
  DATABASE_PORT: "number.port",
  
  // Boolean values (accepts "true"/"false" strings, converts to boolean)
  DEBUG: "boolean",
  
  // Optional variables with defaults
  LOG_LEVEL: "'debug' | 'info' | 'warn' | 'error' = 'info'",
  
  // Optional variables
  "FEATURE_FLAGS?": 'string[]'
});

Link to section: common-patterns#Common patterns

Link to section: configuration-factory#Configuration factory

Create a configuration factory to handle different environments:

import arkenv from 'arkenv';

const createConfig = () => {
  const env = arkenv({
    NODE_ENV: "'development' | 'test' | 'production'",
    DATABASE_HOST: "string.host",
    DATABASE_PORT: "number.port",
  });

  return {
    isProduction: env.NODE_ENV === 'production',
    database: {
      host: env.DATABASE_HOST,
      port: env.DATABASE_PORT,
    }
  };
};

export const config = createConfig();

Link to section: feature-flags#Feature flags

Use environment variables for feature flags:

import arkenv from 'arkenv';

export const env = arkenv({
  "ENABLE_BETA_FEATURES": 'boolean = false',
  "MAINTENANCE_MODE": 'boolean = false',
  "ALLOWED_ORIGINS": 'string[]'
});

Link to section: troubleshooting#Troubleshooting

Link to section: common-issues#Common issues

1. Missing variables

   • Check if .env file exists
   • Verify variable names match exactly
   • Ensure variables are loaded before use

2. Type errors

   • Verify variable types match schema
   • Check for typos in variable names
   • Ensure all required variables are provided

3. Loading order

   • Load environment variables before importing config
   • Consider using a bootstrap file
   • Check framework-specific loading behavior