From 427660d6860c45b406828fb462fb78c81d1196af Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 26 Aug 2025 09:58:35 +0000 Subject: [PATCH] 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 --- BUILDING.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index ba981a8d..d34702c0 100644 --- a/BUILDING.md +++ b/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