Browse Source

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
electron-build-capacitor-config
Matthew Raymer 1 week ago
parent
commit
427660d686
  1. 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

Loading…
Cancel
Save