183 lines
5.7 KiB
Markdown
183 lines
5.7 KiB
Markdown
# App Configuration
|
|
|
|
This document describes the configuration options and mechanisms used in the App.
|
|
|
|
## Environment Variables
|
|
|
|
The application uses environment variables for configuration, which are injected into the application at runtime through `window.appConfig`.
|
|
|
|
### Runtime Environment Variables
|
|
|
|
Environment variables are loaded at runtime, not build time. This allows for different configurations in different environments without rebuilding the application.
|
|
|
|
#### Development Environment
|
|
|
|
In development, environment variables are loaded from `.env` files and injected into the application through `window.appConfig` by the Vite plugin.
|
|
|
|
#### Production Environment
|
|
|
|
In production (Docker), environment variables are loaded from the container environment and injected into the application through `window.appConfig` by the `docker-entrypoint.sh` script.
|
|
|
|
### Environment Variable Naming
|
|
|
|
- All environment variables used by the client application should start with `CLIENT_`
|
|
- These variables are converted to camelCase in `window.appConfig`
|
|
- Example: `CLIENT_API_URL` becomes `window.appConfig.apiUrl`
|
|
|
|
### Available Environment Variables
|
|
|
|
| Environment Variable | Description | Default Value |
|
|
|----------------------|-------------|---------------|
|
|
| `CLIENT_API_URL` | URL of the API server | Required, or can be set to "DETECT" for auto-detection |
|
|
| `CLIENT_BASE_PATH` | Base path of the application | "/" |
|
|
| `CLIENT_APP_NAME` | Name of the application | "App" |
|
|
| `CLIENT_DEBUG` | Enable debug mode | "false" |
|
|
| `CLIENT_MAP_TILE_ENDPOINT` | Endpoint for map tiles | "" |
|
|
| `CLIENT_MAP_TILE_API_KEY` | API key for map tiles | "" |
|
|
|
|
## URL Handling
|
|
|
|
The application uses the built-in `URL` class for proper URL handling to avoid issues with slashes and ensure consistent URL formatting.
|
|
|
|
### URL Utilities
|
|
|
|
The application includes utility functions in `src/shared/lib/url-utils.ts` for common URL operations:
|
|
|
|
#### `joinUrl(base, ...paths)`
|
|
|
|
Safely joins a base URL with path segments.
|
|
|
|
```typescript
|
|
// Example
|
|
const apiUrl = joinUrl('https://api.example.com', 'v1', 'users');
|
|
// Result: https://api.example.com/v1/users
|
|
```
|
|
|
|
#### `createHashUrl(base, basePath, hashPath)`
|
|
|
|
Creates a properly formatted hash URL with the hash fragment after the trailing slash of the base path.
|
|
|
|
```typescript
|
|
// Example
|
|
const url = createHashUrl('https://example.com', 'app', 'users/123');
|
|
// Result: https://example.com/app/#users/123
|
|
```
|
|
|
|
#### `normalizeUrl(url)`
|
|
|
|
Normalizes a URL by ensuring it has a trailing slash.
|
|
|
|
```typescript
|
|
// Example
|
|
const normalizedUrl = normalizeUrl('https://api.example.com/v1');
|
|
// Result: https://api.example.com/v1/
|
|
```
|
|
|
|
#### `cleanupUrl()`
|
|
|
|
Cleans up the current URL by removing query parameters and hash fragments.
|
|
|
|
```typescript
|
|
// Example: Current URL is https://example.com/app/?code=123#/callback
|
|
cleanupUrl();
|
|
// Result: https://example.com/app/
|
|
```
|
|
|
|
### Hash-Based Routing
|
|
|
|
The application uses hash-based routing (`/#`) instead of URL-based routing for better compatibility with static hosting and to avoid server configuration for deep linking.
|
|
|
|
- All routes are prefixed with `/#`
|
|
- The hash fragment always comes after the trailing slash of the base path
|
|
- Example: `https://example.com/app/#users` (correct) vs `https://example.com/app#users` (incorrect)
|
|
|
|
## OIDC Authentication
|
|
|
|
The application uses OIDC for authentication with the following configuration:
|
|
|
|
### OIDC Configuration
|
|
|
|
- The OIDC configuration is fetched from the API server at `/apiendpoint/oidc.json`
|
|
- The OIDC provider is separate from the API provider
|
|
- The API provider gives information about the OIDC provider location
|
|
|
|
### OIDC URLs
|
|
|
|
- Authority URL: The URL of the OIDC provider, normalized to ensure it has a trailing slash
|
|
- Redirect URI: The URL to redirect to after authentication, using hash-based routing
|
|
- Post-Logout Redirect URI: The URL to redirect to after logout, using hash-based routing
|
|
|
|
### OIDC Callback Handling
|
|
|
|
- After authentication, the callback URL is cleaned up to remove query parameters and hash fragments
|
|
- The user is redirected to the intended page or the home page
|
|
|
|
## API URL Configuration
|
|
|
|
The API URL can be configured in several ways:
|
|
|
|
### Static Configuration
|
|
|
|
Set the `CLIENT_API_URL` environment variable to the URL of the API server.
|
|
|
|
### Auto-Detection
|
|
|
|
Set the `CLIENT_API_URL` environment variable to `"DETECT"` to automatically detect the API URL based on the current window location.
|
|
|
|
The auto-detection logic:
|
|
1. Takes the current window location (e.g., `https://www.example.com/path1/path2/path3`)
|
|
2. Extracts the first path segment (e.g., `path1`)
|
|
3. Constructs a new URL with just the origin and first path segment (e.g., `https://www.example.com/path1/`)
|
|
|
|
Examples:
|
|
- `https://www.example.com/path1/path2/path3/` → `https://www.example.com/path1/`
|
|
- `https://www.example.com/` → `https://www.example.com/`
|
|
- `https://www.example.com/path1` → `https://www.example.com/path1/`
|
|
|
|
If auto-detection fails, a fatal error is logged and the application does not proceed.
|
|
|
|
## Accessing Configuration in Code
|
|
|
|
### API URL
|
|
|
|
```typescript
|
|
// Use OpenAPI.BASE for the normalized API URL
|
|
import { OpenAPI } from "@merchant-api/core/OpenAPI";
|
|
|
|
const apiUrl = OpenAPI.BASE;
|
|
```
|
|
|
|
### Other Configuration
|
|
|
|
```typescript
|
|
// Access environment variables through window.appConfig
|
|
const appName = window.appConfig.appName;
|
|
const debug = window.appConfig.debug;
|
|
```
|
|
|
|
## Development Scripts
|
|
|
|
### Generate App Config
|
|
|
|
```bash
|
|
npm run generate-app-config
|
|
```
|
|
|
|
Generates the `app-config.js` file in the `public` directory based on environment variables.
|
|
|
|
### Build
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
Builds the application for production.
|
|
|
|
### Development Server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Starts the development server with hot reloading.
|