Client-Side Environment Variables

This document explains the client-side environment variables used in the application.

Available Variables

The application uses the following client-side environment variables, all prefixed with CLIENT_:

Variable	Description	Default
`CLIENT_API_URL`	Base URL for backend API requests	`https://localhost:7205`
`CLIENT_BASE_PATH`	Base path for client-side routing	`/`
`CLIENT_APP_NAME`	Application name displayed in UI	`Merchant Operator App`
`CLIENT_DEBUG`	Enable debug mode	`false`

How to Set Variables

Development Environment

For local development, set these variables in:

.env.development (shared development settings)
.env.development.local (personal development settings, gitignored)

Example .env.development:

CLIENT_BASE_PATH=/
CLIENT_API_URL=https://localhost:7205
CLIENT_APP_NAME=Merchant Operator App
CLIENT_DEBUG=true

Vite automatically makes variables prefixed with CLIENT_ available via import.meta.env. Remember to restart the Vite dev server after changing .env files.

Docker Environment

For Docker deployments, environment variables are configured at runtime through Docker Compose or environment variables:

Using docker-compose.yml

services:
  merchant-operator-app:
    environment:
      - CLIENT_API_URL=https://api.example.com
      - CLIENT_BASE_PATH=/merchant-app
      - CLIENT_APP_NAME=Merchant Operator App
      - CLIENT_DEBUG=false

Using docker-compose.override.yml

Create a docker-compose.override.yml file from the template and set your environment-specific values:

services:
  merchant-operator-app:
    environment:
      - CLIENT_API_URL=https://api.example.com
      - CLIENT_BASE_PATH=/merchant-app
      - CLIENT_APP_NAME=Merchant Operator App
      - CLIENT_DEBUG=false

Using .env file with docker-compose

Create a .env file in the same directory as your docker-compose.yml:

# .env
CLIENT_API_URL=https://api.example.com
CLIENT_BASE_PATH=/merchant-app
CLIENT_APP_NAME=Merchant Operator App
CLIENT_DEBUG=false
# ... other variables

Using Docker run command

docker run -e CLIENT_BASE_PATH=/merchant-app -e CLIENT_API_URL=https://api.example.com -e CLIENT_APP_NAME="Merchant Operator App" -e CLIENT_DEBUG=false your-image-name

How Runtime Environment Variables Work

The application uses a special mechanism to handle environment variables at runtime in Docker:

When the Docker container starts, the docker-entrypoint.sh script runs
The script extracts all environment variables starting with CLIENT_ from the container's environment
These variables are written to a .env file in the app's directory
The Vite app reads these variables at runtime

This approach allows you to:

Use the same container image in different environments
Change environment variables without rebuilding the image
Pass environment variables through Docker Compose, environment files, or directly via Docker run commands

Accessing Variables in Code

All environment variables are accessed using Vite's import.meta.env object:

// Direct access
const apiUrl = import.meta.env.CLIENT_API_URL;
const basePath = import.meta.env.CLIENT_BASE_PATH;
const appName = import.meta.env.CLIENT_APP_NAME;
const debug = import.meta.env.CLIENT_DEBUG;

Utility functions are available to access common values:

import { getBasePath, getAssetPath } from '../shared/lib/config';

// Get the base path
const basePath = getBasePath(); // "/merchant-app"

// Get a path with the base path prepended
const logoPath = getAssetPath('/images/logo.png'); // "/merchant-app/images/logo.png"

3.9 KiB Raw Blame History