react-spa-template/docs/configuration.md

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.

// 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.

// 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.

// 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.

// 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

// Use OpenAPI.BASE for the normalized API URL
import { OpenAPI } from "@merchant-api/core/OpenAPI";

const apiUrl = OpenAPI.BASE;

Other Configuration

// Access environment variables through window.appConfig
const appName = window.appConfig.appName;
const debug = window.appConfig.debug;

Development Scripts

Generate App Config

npm run generate-app-config

Generates the app-config.js file in the public directory based on environment variables.

Build

npm run build

Builds the application for production.

Development Server

npm run dev

Starts the development server with hot reloading.