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

The CLI or development server loads wrnexus.config.*.
@wrnexus/plugin discovers explicit plugins and installed package manifests.
Contributions are normalized and validated for duplicate IDs, paths, routes, and migrations.
The router combines application and package components/routes/middleware.
.wrn sources compile through plugin AST/code transforms.
SSR renders page and component HTML.
Rendered data-wrnexus-runtime markers are matched against registered client runtimes.
Only referenced runtime scripts are added to the response.
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:

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.

3.8 KiB Raw Permalink Blame History