A Node.js web application template with explicit assets, routes, build, and deployment boundaries.
- Features
- Requirements
- Setup
- Usage
- Development
- Testing
- Troubleshooting
- Security
- Configuration
- Operations
- Routes
- Assets
- Development server
- Build
- Deployment
- Support
- Links
- License
Start with a Fastify server, a browser app shell, a validated API example, and Docker support. Read the web application guide for setup and operation details.
Use Node.js 26 or later. Use npm to install dependencies and run repository commands.
Create a repository from this template. Run npm ci from its root directory.
Follow the web application guide to configure, build, and run the app. Read release notes for version history.
Read AGENTS.md and the specifications index before changing files. Keep server code in src/backend/ and browser code in src/frontend/.
Run npm test for aggregate validation. Pass test file paths to run focused tests. See the web application guide for validation commands.
Check the web application guide for server, API, offline, browser, and container problems.
Keep credentials, private data, and runtime state out of Git. Store secret values in an approved secret store.
Set PORT to set the server port. It defaults to 1020 and accepts integers from 1 through 65535. Set LOG_LEVEL to configure Fastify logging. It defaults to info.
Run npm run build, then run node bin/web-template.mjs. Run docker compose up --build -d to build and start the container on port 1020. Run docker compose down to stop it.
| Method | Path | Result |
|---|---|---|
GET |
/ |
Serves the app page. |
GET |
/client.js |
Serves the browser bundle. |
GET |
/styles.css |
Serves the page styles. |
GET |
/manifest.webmanifest |
Serves app install metadata. |
GET |
/service-worker.js |
Serves the offline worker. |
GET |
/icons/* |
Serves the template icons. |
GET |
/screenshots/* |
Serves the app preview images. |
GET |
/health |
Returns {"status":"ok"}. |
GET |
/ready |
Returns {"status":"ready"}. |
POST |
/api/examples/:exampleId |
Validates an API example request. |
| Other methods | / and asset routes |
Return HTTP 405. |
GET |
Other paths | Returns HTTP 404. |
Keep source assets in public/. The build creates dist/client.js and dist/service-worker.js. The app page, manifest, icons, styles, and preview images come from public/.
Run npm run build, then run node bin/web-template.mjs. Run npm run puppeteer to install Chrome before browser checks. See browser validation.
Run npm run build to bundle src/frontend/client-entry.mjs and the worker entry into dist/. Run npm test to validate the repository.
The GHCR image contains this web app. The workflow publishes ghcr.io/eliware/web-template for version tags that match package.json. Set package visibility and pull access in GitHub. The repository owner maintains the Dockerfile and the linux/amd64 build target. Publication does not deploy the app. Use an approved version tag and its recorded SHA-256 digest for deployment.
For help, questions, or to chat with the author and community, visit:
