137 lines
4.4 KiB
Markdown
137 lines
4.4 KiB
Markdown
# WRNexusJS 0.3 Architecture
|
|
|
|
## Design goals
|
|
|
|
WRNexusJS 0.3 is an additive architecture release focused on one invariant:
|
|
|
|
> A valid `.wrn` file must be parsed, diagnosed, compiled, rendered, hydrated,
|
|
> formatted, migrated, and edited from one shared language model.
|
|
|
|
The release keeps existing application contracts while adding extension seams for
|
|
full-stack data, plugins, partial hydration, observability, tenancy, advanced
|
|
routing, build analysis, jobs, and deployment adapters.
|
|
|
|
## Package boundaries
|
|
|
|
### Language and compilation
|
|
|
|
- `@wrnexus/syntax`: canonical tokens, AST, source positions, diagnostics, and spec
|
|
- `@wrnexus/compiler`: SSR/client code generation and deprecated parser re-exports
|
|
- `@wrnexus/csr`: browser navigation and fine-grained reactive hydration
|
|
- `@wrnexus/reactive`: framework-independent signals, computed values, effects, and batching
|
|
|
|
### Request and application runtime
|
|
|
|
- `@wrnexus/core`: context, middleware, security, typed endpoints, loaders/actions,
|
|
tenant APIs, tracing, feature flags, and performance budgets
|
|
- `@wrnexus/router`: route discovery, matching, groups, optional/catch-all params,
|
|
conflicts, and typed URL generation
|
|
- `@wrnexus/ssr`: document rendering plus string, promise, and async-iterable streaming
|
|
- `@wrnexus/dev-server`: shared dev/production request runtime and portable fetch handlers
|
|
|
|
### Extension and operations
|
|
|
|
- `@wrnexus/plugin`: deterministic plugin ordering and lifecycle hooks
|
|
- `@wrnexus/dev-toolbar`: source-linked page diagnostics
|
|
- `@wrnexus/cli`: build, doctor, config explanation, analyzer, migrations, and generators
|
|
- `@wrnexus/queue`: jobs, priority, concurrency, idempotency, cancellation, cron helpers,
|
|
and workflows
|
|
- `@wrnexus/pubsub`: realtime scaling adapters
|
|
|
|
## Compatibility layers
|
|
|
|
The compiler's former parser, tokenizer, and AST modules re-export the canonical
|
|
syntax package. No existing public compiler import must be changed immediately.
|
|
|
|
The client runtime continues to support legacy hydration scopes, `data-for`, and
|
|
`{#each}` output. New hydration metadata is additive:
|
|
|
|
```html
|
|
<div data-wrn-hydration="stable-id" data-wrn-hydrate="visible" data-wrn-runtime="universal"></div>
|
|
```
|
|
|
|
The updater creates a full application-source backup before source normalization.
|
|
Its migration report lists every changed file.
|
|
|
|
## Request flow
|
|
|
|
```text
|
|
Request
|
|
-> security/CORS/body-size boundary
|
|
-> optional tracing middleware
|
|
-> optional tenant middleware
|
|
-> application middleware
|
|
-> route matcher
|
|
-> loader/API/page/realtime dispatch
|
|
-> SSR document assembly
|
|
-> response cookies/security/compression
|
|
```
|
|
|
|
Development and production use the same `createHandlers` runtime. Production also
|
|
exposes `createProductionHandlers`, a portable web-standard fetch seam used by Bun,
|
|
Node, and future edge/serverless adapters.
|
|
|
|
## Reactive update flow
|
|
|
|
```text
|
|
signal write
|
|
-> dependency invalidation
|
|
-> microtask batch
|
|
-> computed values refresh on demand
|
|
-> only subscribed renderers/effects run
|
|
-> DOM bindings update
|
|
```
|
|
|
|
Renderer scheduling is coalesced so repeated writes in one task do not cause a full
|
|
component rerender for each write.
|
|
|
|
## Plugin lifecycle
|
|
|
|
Plugins are ordered deterministically with `enforce`, `before`, and `after`:
|
|
|
|
```text
|
|
configure
|
|
configResolved
|
|
buildStart / configureServer
|
|
transformAst
|
|
plugin diagnostics
|
|
transformCode
|
|
buildEnd
|
|
```
|
|
|
|
Duplicate names and ordering cycles fail with stable plugin errors. Plugin hooks
|
|
are optional and the absence of plugins has zero behavioral effect.
|
|
|
|
## Build outputs
|
|
|
|
A production build can emit:
|
|
|
|
- compiled route/component modules
|
|
- source maps when enabled
|
|
- route and asset measurements
|
|
- `dist/build-report.json`
|
|
- performance-budget violations
|
|
- generated production entry with security, observability, tenancy, storage,
|
|
databases, realtime, mobile, PWA, and SEO configuration
|
|
|
|
Use:
|
|
|
|
```bash
|
|
wrnexus config . --explain
|
|
wrnexus build .
|
|
wrnexus analyze .
|
|
wrnexus doctor .
|
|
```
|
|
|
|
## Stability levels
|
|
|
|
- **Stable**: existing behavior, canonical syntax ownership, diagnostics, router
|
|
compatibility, typed core primitives, build reports, migration safety
|
|
- **Additive stable API**: plugin contracts, tracing, tenancy, loaders/actions,
|
|
endpoint definitions, job definitions
|
|
- **Experimental runtime behavior**: server components, broader streaming boundaries,
|
|
custom adapter implementations, and plugin transforms can be gated in config
|
|
|
|
Experimental flags make feature adoption explicit without forcing existing apps to
|
|
change their runtime behavior.
|