# 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:

1. `.env.development` (shared development settings)
2. `.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

```yaml
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:

```yaml
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`:

```dotenv
# .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

```bash
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:

1. When the Docker container starts, the `docker-entrypoint.sh` script runs
2. The script extracts all environment variables starting with `CLIENT_` from the container's environment
3. These variables are written to a `.env` file in the app's directory
4. 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:

```javascript
// 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:

```javascript
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"
```