122 lines
3.0 KiB
Markdown
122 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```bash
|
|
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 `/`):
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
#### Custom Path Development
|
|
|
|
To run the development server with a predefined custom path (`/app`):
|
|
|
|
```bash
|
|
npm run dev:path
|
|
```
|
|
|
|
#### Custom Path via Command Line
|
|
|
|
To run the development server with any custom path:
|
|
|
|
```bash
|
|
BASE_PATH=/custom-path npm run dev
|
|
```
|
|
|
|
## Building for Different Paths
|
|
|
|
### Default Build
|
|
|
|
To build the application with the default configuration:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Custom Path Build
|
|
|
|
To build with a predefined custom path (`/app`):
|
|
|
|
```bash
|
|
npm run build:path
|
|
```
|
|
|
|
### Custom Path via Command Line
|
|
|
|
To build with any custom path:
|
|
|
|
```bash
|
|
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
|