react-spa-template/docs/local-development.md

Local Development Guide

This guide explains how to run the application locally with different base path configurations.

Environment Variables

The application uses environment variables to configure settings during development. These variables can be set in several ways:

1. In .env.development (shared development settings)
2. In .env.development.local (personal development settings, gitignored)
3. Via command line when running scripts

Client-Side Environment Variables

Variables with the CLIENT_ prefix will be available in the browser through the window.appConfig object. For example:

CLIENT_API_URL=https://localhost:7205
CLIENT_APP_NAME=My App
CLIENT_DEBUG=true

These will be available in the browser as:

window.appConfig.apiUrl // "https://localhost:7205"
window.appConfig.appName // "My App"
window.appConfig.debug // "true"

Variable names are converted from CLIENT_SNAKE_CASE to camelCase automatically.

Setting Up Local Development

Basic Setup

1. Copy the template file to create your local environment configuration:

cp .env.development.local.template .env.development.local

2. Edit .env.development.local to set your preferred base path:

BASE_PATH=/your-path

Running the Development Server

Default Development (Root Path)

To run the development server with the default configuration (usually root path /):

npm run dev

Custom Path Development

To run the development server with a predefined custom path (/Merchant-app):

npm run dev:path

Custom Path via Command Line

To run the development server with any custom path:

BASE_PATH=/custom-path npm run dev

Building for Different Paths

Default Build

To build the application with the default configuration:

npm run build

Custom Path Build

To build with a predefined custom path (/Merchant-app):

npm run build:path

Custom Path via Command Line

To build with any custom path:

BASE_PATH=/custom-path npm run build

How It Works

1. The Vite configuration reads the BASE_PATH environment variable
2. It dynamically updates the config.js file with the appropriate base path during development
3. The application uses this configuration to construct URLs correctly
4. In production, the docker-entrypoint.sh script replaces a placeholder in config.js with the actual base path

Testing Different Paths

To test how the application behaves with different base paths:

1. Set a custom base path in .env.development.local or via command line
2. Run the development server
3. Verify that all links and assets load correctly
4. Test navigation within the application

Troubleshooting

• If assets are not loading, check that you're using the getAssetPath() function for all asset URLs
• If the base path is not being applied, make sure the environment variable is being set correctly
• Check the console for any error messages related to path configuration