forked from trent_larson/crowd-funder-for-time-pwa
docs: enhance serve command documentation in BUILDING.md
- Clarify build:web:serve purpose as "production testing" - Add "Why Use serve?" section explaining benefits - Document SPA routing support for deep links (/discover, /account) - Add dedicated "Local Serving with serve" technical section - Explain server options (npx serve vs Python fallback) - Improve developer understanding of when and why to use serve Fixes documentation gap identified in serve command usage
This commit is contained in:
29
BUILDING.md
29
BUILDING.md
@@ -251,7 +251,7 @@ npm run build:web:dev # Start development server with hot reload
|
|||||||
npm run build:web # Development build (starts dev server with hot reload)
|
npm run build:web # Development build (starts dev server with hot reload)
|
||||||
npm run build:web:test # Test environment build (optimized for testing)
|
npm run build:web:test # Test environment build (optimized for testing)
|
||||||
npm run build:web:prod # Production build (optimized for production)
|
npm run build:web:prod # Production build (optimized for production)
|
||||||
npm run build:web:serve # Build and serve locally (builds then serves)
|
npm run build:web:serve # Build and serve locally for production testing
|
||||||
|
|
||||||
# Docker builds
|
# Docker builds
|
||||||
npm run build:web:docker # Development build with Docker containerization
|
npm run build:web:docker # Development build with Docker containerization
|
||||||
@@ -269,6 +269,12 @@ Start the development server using `npm run build:web:dev` or `npm run build:web
|
|||||||
2. The built files will be in the `dist` directory
|
2. The built files will be in the `dist` directory
|
||||||
3. To test the production build locally, use `npm run build:web:serve` (builds then serves)
|
3. To test the production build locally, use `npm run build:web:serve` (builds then serves)
|
||||||
|
|
||||||
|
**Why Use `serve`?**
|
||||||
|
- **Production Testing**: Test your optimized production build locally before deployment
|
||||||
|
- **SPA Routing Validation**: Verify deep linking and navigation work correctly (handles routes like `/discover`, `/account`)
|
||||||
|
- **Performance Testing**: Test the minified and optimized build locally
|
||||||
|
- **Deployment Validation**: Ensure built files work correctly when served by a real HTTP server
|
||||||
|
|
||||||
You'll likely want to use test locations for the Endorser & image & partner servers; see "DEFAULT_ENDORSER_API_SERVER" & "DEFAULT_IMAGE_API_SERVER" & "DEFAULT_PARTNER_API_SERVER" below.
|
You'll likely want to use test locations for the Endorser & image & partner servers; see "DEFAULT_ENDORSER_API_SERVER" & "DEFAULT_IMAGE_API_SERVER" & "DEFAULT_PARTNER_API_SERVER" below.
|
||||||
|
|
||||||
### Web Build Script Details
|
### Web Build Script Details
|
||||||
@@ -288,7 +294,7 @@ All web build commands use the `./scripts/build-web.sh` script, which provides:
|
|||||||
- **Clean Build**: Removes previous `dist/` directory
|
- **Clean Build**: Removes previous `dist/` directory
|
||||||
- **Vite Build**: Executes `npx vite build --config vite.config.web.mts`
|
- **Vite Build**: Executes `npx vite build --config vite.config.web.mts`
|
||||||
- **Docker Support**: Optional Docker containerization
|
- **Docker Support**: Optional Docker containerization
|
||||||
- **Local Serving**: Built-in HTTP server for testing builds
|
- **Local Serving**: Built-in HTTP server for testing builds with SPA routing support
|
||||||
|
|
||||||
**Direct Script Usage:**
|
**Direct Script Usage:**
|
||||||
|
|
||||||
@@ -324,6 +330,25 @@ All web build commands use the `./scripts/build-web.sh` script, which provides:
|
|||||||
- `5` - Serve command failed
|
- `5` - Serve command failed
|
||||||
- `6` - Invalid build mode
|
- `6` - Invalid build mode
|
||||||
|
|
||||||
|
### Local Serving with `serve`
|
||||||
|
|
||||||
|
The `serve` functionality provides a local HTTP server for testing production builds:
|
||||||
|
|
||||||
|
**What It Does:**
|
||||||
|
1. **Builds** the application using Vite
|
||||||
|
2. **Serves** the built files from the `dist/` directory
|
||||||
|
3. **Handles SPA Routing** - serves `index.html` for all routes (fixes 404s on `/discover`, `/account`, etc.)
|
||||||
|
|
||||||
|
**Server Options:**
|
||||||
|
- **Primary**: `npx serve -s dist -l 8080` (recommended - full SPA support)
|
||||||
|
- **Fallback**: Python HTTP server (limited SPA routing support)
|
||||||
|
|
||||||
|
**Use Cases:**
|
||||||
|
- Testing production builds before deployment
|
||||||
|
- Validating SPA routing behavior
|
||||||
|
- Performance testing of optimized builds
|
||||||
|
- Debugging production build issues locally
|
||||||
|
|
||||||
### Compile and minify for test & production
|
### Compile and minify for test & production
|
||||||
|
|
||||||
- If there are DB changes: before updating the test server, open browser(s) with
|
- If there are DB changes: before updating the test server, open browser(s) with
|
||||||
|
|||||||
Reference in New Issue
Block a user