Environment Configuration

Overview

Proper environment configuration ensures ESBO Web runs consistently across development, staging, and production environments. This guide covers Node.js requirements, environment variables, and configuration for different deployment targets.

Node.js Requirements

Version Compatibility

ESBO Web requires:

Node.js: 18.0.0 or higher (recommended: 18.x LTS or 20.x LTS)
npm: 9.0.0 or higher (comes with Node.js)

Vite 7.3.1 requires Node.js 18+ for optimal performance and ES module support.

Checking Your Version

Verify your current Node.js version:

node --version
npm --version

Installing Node.js

Using NVM (Recommended)

Node Version Manager allows easy switching between Node.js versions:

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20 LTS
nvm install 20
nvm use 20

# Set as default
nvm alias default 20

Direct Installation

Download from nodejs.org:

Choose LTS (Long Term Support) version
Follow installer instructions
Verify installation with node --version

Using Package Managers

macOS (Homebrew):

brew install node@20

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows (Chocolatey):

choco install nodejs-lts

Environment Variables

Vite Environment Variables

Vite exposes environment variables to your client-side code using the VITE_ prefix.

Currently, ESBO Web doesn’t require environment variables for basic functionality. However, you may need them for API integrations or feature flags.

Creating Environment Files

Create environment files in your project root:

# .env.local (local development, git-ignored)
VITE_API_URL=http://localhost:3000
VITE_ENABLE_ANALYTICS=false

# .env.production (production builds)
VITE_API_URL=https://api.esbo.example.com
VITE_ENABLE_ANALYTICS=true

Environment File Priority

Vite loads environment files in this order (later files override earlier ones):

.env - Loaded in all cases
.env.local - Loaded in all cases, ignored by git
.env.[mode] - Loaded only in specified mode
.env.[mode].local - Loaded only in specified mode, ignored by git

Never commit .env.local or any files containing secrets to version control. Add them to .gitignore.

Using Environment Variables

Access environment variables in your code:

// In any .jsx/.js file
const apiUrl = import.meta.env.VITE_API_URL
const isProduction = import.meta.env.PROD
const isDevelopment = import.meta.env.DEV

console.log('API URL:', apiUrl)
console.log('Mode:', import.meta.env.MODE)

Built-in Variables

Vite provides these variables automatically:

import.meta.env.MODE: 'development' or 'production'
import.meta.env.PROD: true in production
import.meta.env.DEV: true in development
import.meta.env.BASE_URL: Base URL of the app

Development vs Production

Development Environment

Start development server:

npm run dev

Characteristics:

Runs on http://localhost:5173
Hot Module Replacement (HMR) enabled
Verbose error messages
Source maps included
No optimization or minification
Fast rebuild times

Environment:

import.meta.env.MODE === 'development'
import.meta.env.DEV === true

Production Environment

Build for production:

npm run build

Characteristics:

Optimized and minified bundles
Tree-shaking applied
Asset hashing for cache busting
No development warnings
Optimized for performance

Environment:

import.meta.env.MODE === 'production'
import.meta.env.PROD === true

Preview Production Locally

Test production build on local machine:

npm run build
npm run preview

The preview server runs on http://localhost:4173 by default and serves the built dist/ directory.

Deployment Target Configuration

Vercel

Automatic configuration (detected by Vercel):

Framework: Vite
Build Command: npm run build
Output Directory: dist
Node.js Version: 18.x (default)

Environment variables in Vercel:

Go to Project Settings → Environment Variables
Add variables with VITE_ prefix
Select environments: Production, Preview, Development
Redeploy to apply changes

Vercel automatically makes environment variables available during build time.

Netlify

Build settings:

netlify.toml

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

Environment variables:

Add in Site Settings → Environment Variables
Use VITE_ prefix for client-side variables

GitHub Pages

Configure base path in vite.config.js:

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: '/repository-name/',
  plugins: [react()],
})

GitHub Actions workflow:

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Docker

Multi-stage Dockerfile:

Dockerfile

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine

COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

nginx.conf:

nginx.conf

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(?:css|js|jpg|jpeg|gif|png|svg|ico|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Configuration Best Practices

Security

Never expose secrets in client-side code. Environment variables prefixed with VITE_ are embedded in the client bundle and visible to users.

Safe for client-side:

VITE_API_URL=https://api.example.com
VITE_APP_VERSION=1.0.0
VITE_ENABLE_FEATURE_X=true

Never in client-side:

# These should NEVER have VITE_ prefix
DATABASE_URL=...
API_SECRET_KEY=...
PRIVATE_KEY=...

Git Ignore Configuration

Ensure your .gitignore includes:

.gitignore

# Environment files
.env.local
.env.*.local

# Build output
dist
dist-ssr
*.local

# Dependencies
node_modules

# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*

Type Safety for Environment Variables

Create type definitions for environment variables:

vite-env.d.ts

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_ENABLE_ANALYTICS: string
  // Add more variables as needed
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

Troubleshooting

Environment Variables Not Loading

Check prefix

Ensure variables start with VITE_

Restart dev server

Environment changes require server restart:

# Stop dev server (Ctrl+C)
npm run dev

Verify file location

Environment files must be in project root (same directory as package.json)

Check file naming

Files must be named exactly: .env, .env.local, .env.production, etc.

Node.js Version Mismatch

If you encounter version issues:

# Clear npm cache
npm cache clean --force

# Remove node_modules and lock file
rm -rf node_modules package-lock.json

# Reinstall with correct Node.js version
npm install

Build Fails in CI/CD

Most CI/CD issues are caused by missing environment variables or incorrect Node.js versions.

Checklist:

Verify Node.js version in CI configuration
Ensure all required environment variables are set
Check that build command matches package.json
Verify dependencies are installed correctly
Review build logs for specific errors

Next Steps

Set up environment-specific configurations
Configure deployment pipelines
Add monitoring and analytics
Implement feature flags
Set up automated testing across environments

Get Started

Development

Deployment

Reference

Environment Configuration

Overview

Node.js Requirements

Version Compatibility

Checking Your Version

Installing Node.js

Environment Variables

Vite Environment Variables

Creating Environment Files

Environment File Priority

Using Environment Variables

Built-in Variables

Development vs Production

Development Environment

Production Environment

Preview Production Locally

Deployment Target Configuration

Vercel

Netlify

GitHub Pages

Docker

Configuration Best Practices

Security

Git Ignore Configuration

Type Safety for Environment Variables

Troubleshooting

Environment Variables Not Loading

Node.js Version Mismatch

Build Fails in CI/CD

Next Steps

Build docs developers (and LLMs) love

Get Started

Development

Deployment

Reference

​Overview

​Node.js Requirements

​Version Compatibility

​Checking Your Version

​Installing Node.js

​Environment Variables

​Vite Environment Variables

​Creating Environment Files

​Environment File Priority

​Using Environment Variables

​Built-in Variables

​Development vs Production

​Development Environment

​Production Environment

​Preview Production Locally

​Deployment Target Configuration

​Vercel

​Netlify

​GitHub Pages

​Docker

​Configuration Best Practices

​Security

​Git Ignore Configuration

​Type Safety for Environment Variables

​Troubleshooting

​Environment Variables Not Loading

​Node.js Version Mismatch

​Build Fails in CI/CD

​Next Steps

Build docs developers (and LLMs) love

Overview

Node.js Requirements

Version Compatibility

Checking Your Version

Installing Node.js

Environment Variables

Vite Environment Variables

Creating Environment Files

Environment File Priority

Using Environment Variables

Built-in Variables

Development vs Production

Development Environment

Production Environment

Preview Production Locally

Deployment Target Configuration

Vercel

Netlify

GitHub Pages

Docker

Configuration Best Practices

Security

Git Ignore Configuration

Type Safety for Environment Variables

Troubleshooting

Environment Variables Not Loading

Node.js Version Mismatch

Build Fails in CI/CD

Next Steps