Environment Variables

Environment Variables

This guide covers all environment variables used in IONFLOW Frontend.

Overview

Environment variables are managed using Vite’s built-in support. All variables must be prefixed with VITE_ to be exposed to the application.

Configuration Files

File	Purpose	Git Tracked
.env	Default values	Yes
.env.local	Local overrides	No
.env.development	Development mode	Yes
.env.production	Production mode	Yes
.env.[mode].local	Mode-specific local	No

Variable Reference

API Configuration

# Backend API URL
VITE_API_URL=http://localhost:8000/api

# API Version
VITE_API_VERSION=v1

# Gateway API URL
VITE_GATEWAY_URL=http://localhost:8001

Authentication (Keycloak)

# Keycloak Server URL
VITE_KEYCLOAK_URL=http://localhost:8080

# Keycloak Realm
VITE_KEYCLOAK_REALM=ionflow

# Keycloak Client ID
VITE_KEYCLOAK_CLIENT_ID=ionflow-frontend

# Enable Keycloak (true/false)
VITE_KEYCLOAK_ENABLED=true

Feature Flags

# Enable Vue DevTools
VITE_ENABLE_DEV_TOOLS=true

# Enable debug mode
VITE_DEBUG_MODE=false

# Enable mock API
VITE_MOCK_API=false

Application Settings

# Application title
VITE_APP_TITLE=IONFLOW

# Default language (en/es)
VITE_DEFAULT_LOCALE=en

# Items per page default
VITE_DEFAULT_PAGE_SIZE=20

Usage in Code

Accessing Variables

// Direct access
const apiUrl = import.meta.env.VITE_API_URL;

// With type safety
const config = {
  apiUrl: import.meta.env.VITE_API_URL as string,
  isDebug: import.meta.env.VITE_DEBUG_MODE === 'true',
};

Type Definitions

Add to env.d.ts:

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

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_API_VERSION: string;
  readonly VITE_KEYCLOAK_URL: string;
  readonly VITE_KEYCLOAK_REALM: string;
  readonly VITE_KEYCLOAK_CLIENT_ID: string;
  readonly VITE_KEYCLOAK_ENABLED: string;
  readonly VITE_ENABLE_DEV_TOOLS: string;
  readonly VITE_DEBUG_MODE: string;
  readonly VITE_APP_TITLE: string;
  readonly VITE_DEFAULT_LOCALE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Environment-Specific Configurations

Development

.env.development

VITE_API_URL=http://localhost:8000/api
VITE_KEYCLOAK_URL=http://localhost:8080
VITE_ENABLE_DEV_TOOLS=true
VITE_DEBUG_MODE=true

Staging

.env.staging

VITE_API_URL=https://staging-api.ionflow.com/api
VITE_KEYCLOAK_URL=https://staging-auth.ionflow.com
VITE_ENABLE_DEV_TOOLS=true
VITE_DEBUG_MODE=false

Production

.env.production

VITE_API_URL=https://api.ionflow.com/api
VITE_KEYCLOAK_URL=https://auth.ionflow.com
VITE_ENABLE_DEV_TOOLS=false
VITE_DEBUG_MODE=false

Security Considerations

Do NOT expose

• API keys or secrets
• Database credentials
• Private encryption keys
• Internal service URLs

Safe to expose

• Public API endpoints
• Feature flags
• UI configuration
• Public Keycloak settings

Build-Time vs Runtime

Environment variables are replaced at build time. This means:

// ✅ Works - variable is replaced
const url = import.meta.env.VITE_API_URL;

// ❌ Won't work - dynamic access
const key = 'VITE_API_URL';
const url = import.meta.env[key];

Docker Configuration

For Docker deployments, pass variables at runtime:

# Dockerfile
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL

RUN pnpm build

# Build with variables
docker build --build-arg VITE_API_URL=https://api.example.com -t ionflow .

CI/CD Integration

GitHub Actions

jobs:
  build:
    steps:
      - name: Build
        env:
          VITE_API_URL: ${{ secrets.API_URL }}
          VITE_KEYCLOAK_URL: ${{ secrets.KEYCLOAK_URL }}
        run: pnpm build

Troubleshooting

Variables Not Available

1. Ensure prefix is VITE_
2. Restart development server after changes
3. Check file is not in .gitignore (for shared configs)

Wrong Environment

# Check current mode
console.log(import.meta.env.MODE);

# Force specific mode
pnpm dev --mode staging
pnpm build --mode production

Related

• Installation
• Development
• Deployment Guide