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:test # Test environment build (optimized for testing)
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
### 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
|
||||
- **Vite Build**: Executes `npx vite build --config vite.config.web.mts`
|
||||
- **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:**
|
||||
|
||||
@@ -324,6 +330,25 @@ All web build commands use the `./scripts/build-web.sh` script, which provides:
|
||||
- `5` - Serve command failed
|
||||
- `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
|
||||
|
||||
- If there are DB changes: before updating the test server, open browser(s) with
|
||||
|
||||
Reference in New Issue
Block a user