121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# 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 | `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=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:
|
|
spa-app-app:
|
|
environment:
|
|
- CLIENT_API_URL=https://api.example.com
|
|
- CLIENT_BASE_PATH=/app
|
|
- CLIENT_APP_NAME=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:
|
|
spa-app-app:
|
|
environment:
|
|
- CLIENT_API_URL=https://api.example.com
|
|
- CLIENT_BASE_PATH=/app
|
|
- CLIENT_APP_NAME=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=/app
|
|
CLIENT_APP_NAME=App
|
|
CLIENT_DEBUG=false
|
|
# ... other variables
|
|
```
|
|
|
|
#### Using Docker run command
|
|
|
|
```bash
|
|
docker run -e CLIENT_BASE_PATH=/app -e CLIENT_API_URL=https://api.example.com -e CLIENT_APP_NAME="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(); // "/app"
|
|
|
|
// Get a path with the base path prepended
|
|
const logoPath = getAssetPath('/images/logo.png'); // "/app/images/logo.png"
|
|
```
|