69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# WRNexusJS 0.4 architecture
|
|
|
|
## Goals
|
|
|
|
WRNexusJS 0.4 keeps the existing SSR-first model while making advanced systems installable without application-owned copies or manual wiring. The framework remains conservative: HTML is rendered on the server, the reactive runtime loads only for reactive pages, and package browser code loads only when its component or markup declares a runtime requirement.
|
|
|
|
## Request and render path
|
|
|
|
1. The CLI or development server loads `wrnexus.config.*`.
|
|
2. `@wrnexus/plugin` discovers explicit plugins and installed package manifests.
|
|
3. Contributions are normalized and validated for duplicate IDs, paths, routes, and migrations.
|
|
4. The router combines application and package components/routes/middleware.
|
|
5. `.wrn` sources compile through plugin AST/code transforms.
|
|
6. SSR renders page and component HTML.
|
|
7. Rendered `data-wrnexus-runtime` markers are matched against registered client runtimes.
|
|
8. Only referenced runtime scripts are added to the response.
|
|
9. CSR navigation loads newly required runtime chunks, calls `mount`, and calls `unmount` before replacing old page content.
|
|
|
|
## Package contribution model
|
|
|
|
A package can contribute:
|
|
|
|
- component directories
|
|
- client runtimes
|
|
- static or generated assets
|
|
- stylesheet entries and Tailwind scan sources
|
|
- page, API, and realtime routes
|
|
- middleware
|
|
- database migrations
|
|
- DevToolbar panels
|
|
- compiler diagnostics and transforms
|
|
- build and server lifecycle hooks
|
|
|
|
Contributions are declared by a package plugin or by the `wrnexus` field in `package.json`.
|
|
|
|
## Client runtime rules
|
|
|
|
A runtime has a stable ID, source entry, loading policy, module/classic format, and singleton policy. Development serves it from `/__wrnexus/assets/`; TypeScript runtime entries are browser-bundled on demand. Production builds emit content-hashed immutable runtime chunks and store their paths in the static server manifest.
|
|
|
|
Runtime code should register:
|
|
|
|
```js
|
|
window.__wrnexusRuntimes = window.__wrnexusRuntimes || {};
|
|
window.__wrnexusRuntimes.example = {
|
|
mount(root) {},
|
|
unmount(root) {},
|
|
};
|
|
```
|
|
|
|
Mount and unmount must be idempotent. Event listeners, observers, audio, timers, and provider widgets must be cleaned up during unmount.
|
|
|
|
## Package assets and styles
|
|
|
|
Package assets use validated framework paths and receive correct MIME and `nosniff` headers. Production stores package assets in content-addressed files while preserving their declared public URLs; immutable caching remains opt-in. Package component directories and style sources are automatically added to application stylesheet processing, so apps do not need manual Tailwind `@source` entries for installed systems.
|
|
|
|
Production stylesheet processing fails closed by default. A Tailwind/PostCSS failure cannot silently ship unprocessed CSS unless the application explicitly selects fallback behavior.
|
|
|
|
## Package migrations
|
|
|
|
Packages can register inline SQL, a SQL file, or an ordered directory. Migration names are namespaced by package migration ID and may target the default or a named database. Development applies application and package migrations through the same migration table. Production copies both into the build output.
|
|
|
|
## Development experience
|
|
|
|
The development server watches application and workspace package component/runtime/style sources. Package `.wrn` changes invalidate both compiled modules and the stylesheet cache. `wrnexus inspect` exposes packages, plugins, routes, assets, runtimes, styles, migrations, and build reports. DevToolbar receives a platform snapshot and package panels.
|
|
|
|
## Compatibility
|
|
|
|
The 0.4 migration removes legacy CAPTCHA script tags, archives manually copied runtime files instead of deleting them, and leaves user-authored application code intact. Existing explicit plugins continue to work and take precedence over automatically discovered plugins with the same name.
|