FWA Kit is the open-source home for reusable Fullstack Web App building blocks. It currently provides a parser-visible startup shell for smooth first paint and a browser-side Local Edge for atomic code releases and network-resilient recovery.
Both packages stay below application policy. Document Shell does not own route content or interaction, and Local Edge does not move authentication, business authority, secrets, or backend data into the browser.
| Package | Purpose | Executable demo |
|---|---|---|
@fullstack-webapp/document-shell |
Build-time document projection and framework-neutral runtime handoff for a stable first screen | Isolated packed Vite consumer in CI; application demo remains a later package consumer |
@fullstack-webapp/local-edge |
Framework-neutral Local Edge integration for Vite applications | local-edge-demo |
@fullstack-webapp/document-shell compiles an application-owned static shell
into Vite's final index.html, keeps it visible while framework resources load,
and removes it after the real application shell commits. It is build-time
projection rather than SSR: the consumer retains its renderer, markup, critical
CSS, manifest values, and framework lifecycle.
pnpm add -D @fullstack-webapp/document-shellStart with the package README, then follow the file-by-file integration guide.
@fullstack-webapp/local-edge provides:
- a build integration that validates one application configuration and builds the app, loader, and Service Worker entries;
- a same-origin loader and client facade for update, recovery, and release-state UI;
- a Service Worker runtime that verifies a complete candidate release before activation; and
- a release publisher that writes the release descriptor and hosting metadata after the Vite bundles exist.
Install the current public prerelease:
pnpm add -D @fullstack-webapp/local-edgeThe package README has the integration example, public API, configuration, guarantees, and version-specific npm link. Its local-edge-demo is the executable React integration and Chromium behavior matrix.
- A candidate release becomes active only after every declared asset passes origin, redirect, media-type, size, and digest checks.
- A failed candidate does not replace the last known good release; existing documents remain pinned to the release they loaded.
- The runtime intercepts only declared control paths, release assets, and navigation ownership. Application APIs, unknown requests, and cross-origin requests retain browser network semantics.
- The network entry remains independently runnable.
localEdgeEnabled: falseis a reversible network-only release policy, not an unregister operation. - Local Edge is not a complete application architecture. Authentication, domain rules, data authority, backend adapters, and production deployment policy remain with the consuming application.
The project is in pre-release development. Public APIs and serialized contracts may change before the first stable release. The automated browser support claim currently covers Chromium, not Firefox or Safari.
| Need | Entry |
|---|---|
| Integrate Local Edge | @fullstack-webapp/local-edge |
| Remove startup white frames with a parser-visible shell | @fullstack-webapp/document-shell |
| Connect Document Shell file by file | Document Shell integration guide |
| Understand runtime owners and dependency direction | Architecture |
| Configure build-time paths and host ownership | Configuration contract |
| Understand the loader, client facade, navigation, or request ownership | Package documentation |
| Run the executable integration | local-edge-demo |
| Verify a local checkout | AGENTS.md |
| Release a package | Releasing |
Use Node.js 24 and pnpm 11.1.1 for a local checkout:
pnpm install --frozen-lockfile
pnpm run cipnpm run ci is the public verification matrix used by pull requests. It runs linting, type checks, package tests, Chromium lifecycle tests, hosting checks, package-content checks, and an isolated packed consumer. Repository CI has read-only permissions and does not publish packages or deploy the demo.
Packages use independent versions and tags in the form <package-slug>@<version>, currently local-edge@<version> and document-shell@<version>. Tag-driven npm trusted publishing is documented in docs/releasing.md.
FWA Kit is not yet accepting external pull requests. Questions, bug reports, and integration feedback are welcome through GitHub Issues. If an external contribution could help, open an Issue first; this guide will be updated when the project is ready to accept pull requests.
- Maintainer and agent source map:
AGENTS.md - Security policy:
SECURITY.md - Source provenance:
PROVENANCE.md - License: MIT
MIT © 2026 Zou Guoqing