@verajs/ssr 0.2.1 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +522 -390
- package/dist/vera/diagnostics.d.ts +20 -0
- package/dist/vera/diagnostics.js +102 -0
- package/dist/vera/escaping.d.ts +155 -0
- package/dist/vera/escaping.js +293 -0
- package/dist/vera/events.d.ts +41 -0
- package/dist/vera/events.js +162 -0
- package/dist/vera/frames.d.ts +38 -0
- package/dist/vera/frames.js +195 -0
- package/dist/vera/index.d.ts +48 -0
- package/dist/vera/index.js +480 -0
- package/{types → dist/vera}/nodes.d.ts +389 -302
- package/dist/vera/nodes.js +2339 -0
- package/dist/vera/parse.d.ts +53 -0
- package/dist/vera/parse.js +485 -0
- package/dist/vera/reflections.d.ts +566 -0
- package/dist/vera/reflections.js +820 -0
- package/dist/vera/registry.d.ts +14 -0
- package/{src → dist}/vera/registry.js +5 -1
- package/dist/vera/report.d.ts +27 -0
- package/dist/vera/report.js +56 -0
- package/dist/vera/scan.d.ts +37 -0
- package/dist/vera/scan.js +143 -0
- package/dist/vera/select.d.ts +40 -0
- package/dist/vera/select.js +261 -0
- package/dist/vera/serializer.d.ts +39 -0
- package/dist/vera/serializer.js +1521 -0
- package/dist/vera/shim.d.ts +42 -0
- package/dist/vera/shim.js +853 -0
- package/dist/vera/slots.d.ts +5 -0
- package/dist/vera/slots.js +104 -0
- package/dist/vera/stylesheets.d.ts +62 -0
- package/dist/vera/stylesheets.js +180 -0
- package/dist/vera/tokenizer.d.ts +32 -0
- package/dist/vera/tokenizer.js +553 -0
- package/dist/vera/types.d.ts +121 -0
- package/dist/vera/views.d.ts +63 -0
- package/dist/vera/views.js +245 -0
- package/package.json +12 -13
- package/src/vera/escaping.js +0 -135
- package/src/vera/events.js +0 -164
- package/src/vera/frames.js +0 -102
- package/src/vera/index.js +0 -1187
- package/src/vera/nodes.js +0 -2294
- package/src/vera/parse.js +0 -381
- package/src/vera/reflections.js +0 -811
- package/src/vera/select.js +0 -234
- package/src/vera/serializer.js +0 -1080
- package/src/vera/shim.js +0 -761
- package/src/vera/stylesheets.js +0 -155
- package/src/vera/views.js +0 -240
- package/types/escaping.d.ts +0 -27
- package/types/events.d.ts +0 -4
- package/types/frames.d.ts +0 -12
- package/types/index.d.ts +0 -13
- package/types/parse.d.ts +0 -19
- package/types/reflections.d.ts +0 -657
- package/types/registry.d.ts +0 -8
- package/types/select.d.ts +0 -5
- package/types/serializer.d.ts +0 -26
- package/types/shim.d.ts +0 -23
- package/types/stylesheets.d.ts +0 -53
- package/types/views.d.ts +0 -26
package/README.md
CHANGED
|
@@ -1,403 +1,535 @@
|
|
|
1
1
|
# @verajs/ssr
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
no
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
request
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
and `getAttribute('data-flag')` are one attribute and an `attributes` entry spelled `User-ID`
|
|
185
|
-
still matches an `observedAttributes` entry spelled `user-id`; an element created through
|
|
186
|
-
`createElementNS` outside the HTML namespace keeps its case, so an SVG `viewBox` survives.
|
|
3
|
+
Server-side rendering for VeraJS components. Node only, plain ESM, **zero dependencies** — no jsdom,
|
|
4
|
+
no parse5, no lit, no acorn. Components render to **declarative shadow DOM**, and the renderer's
|
|
5
|
+
`hydration` module (`wire([renderer, hydration])`) adopts that markup in the browser without re-creating it.
|
|
6
|
+
|
|
7
|
+
**Light-DOM slots** are distributed on the server while `@verajs/renderer/slots` is wired: each filled slot is written
|
|
8
|
+
with the two comments the client keeps around it (`<!--[-->` … `<!--]-->`), and the host states its light tree in
|
|
9
|
+
`data-vm-light`. A hydrating page reads that through one more module, wired only where both are used:
|
|
10
|
+
`wire([renderer, hydration, slots, hydrateSlots])` (`@verajs/renderer/hydrate-slots`). Render and hydrate with
|
|
11
|
+
matching releases of `@verajs/ssr` and `@verajs/renderer` — the statement carries a format number, and a page in
|
|
12
|
+
another format renders fresh, its content kept.
|
|
13
|
+
|
|
14
|
+
**Hydrate what this renders: wire `hydration` on the client** (`wire([renderer, hydration])`). Without it the client renders
|
|
15
|
+
beside the server's markup — two copies — except a light-slots host, which re-renders once or, holding light content,
|
|
16
|
+
stands as served with `hydration-unwired`.
|
|
17
|
+
|
|
18
|
+
**Wire `slots` on the client AND here:** without it this server writes no light-tree statement, so the client takes
|
|
19
|
+
every component it rendered for client-made and renders it fresh — its markup kept, hidden — with no warning possible.
|
|
20
|
+
|
|
21
|
+
**Serve the HTML unmodified — comments included.** Hydration adopts those slot comments. An HTML minifier that strips
|
|
22
|
+
comments removes them, and hydration then treats that component as a mismatch: the standard fallback warning and a
|
|
23
|
+
fresh render, as React, Lit and Solid treat a missing marker of theirs.
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import { renderToString } from '@verajs/ssr'; // first — it installs the DOM the renderer needs
|
|
27
|
+
|
|
28
|
+
const { html, styles, title } = await renderToString(new URL('./components/app.js', import.meta.url), {
|
|
29
|
+
attributes: { 'user-id': id }, // an object: names checked, values escaped
|
|
30
|
+
props: { rows }, // structured data — an attribute can only carry a string
|
|
31
|
+
location: request.url, // this request's URL, for anything that reads one
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
response.end(`<!doctype html><title>${escape(title)}</title><style>${styles}</style>${html}`);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`html` is the component's markup, its shadow root serialized as `<template shadowrootmode>`. `styles`
|
|
38
|
+
is the light-DOM CSS for the page's `<style>` (already escaped for that element — see
|
|
39
|
+
[Styles](#styles)). `title` is `document.title` as the render left it, which is how a shell names its
|
|
40
|
+
page. `examples/ssr-node/server-native.mjs` is a complete server on bare `node:http` serving the whole
|
|
41
|
+
round trip, hydration included.
|
|
42
|
+
|
|
43
|
+
The package is TypeScript, compiled file by file to `dist` (no bundling, no minification), with its `.d.ts` files
|
|
44
|
+
beside it for TypeScript consumers.
|
|
45
|
+
|
|
46
|
+
## Two entry points
|
|
47
|
+
|
|
48
|
+
| | |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| `renderToString(url, options?)` | synchronous end to end; the fastest path, and the right one for most components |
|
|
51
|
+
| `renderToStringAsync(url, options?)` | **awaits** the lifecycle — an `async connectedCallback`, and work a frame starts — so a component that loads data, or **a routed app's first view**, is in the first response |
|
|
52
|
+
|
|
53
|
+
Both take the same options, return the same `{ html, styles, title }`, and share everything that
|
|
54
|
+
decides what to emit — scanner, serializer, instance preparation, page assembly.
|
|
55
|
+
`tests/ssr-async-parity.test.mjs` renders every fixture through both and compares.
|
|
56
|
+
|
|
57
|
+
**Use the async one for a router.** `initRouter` works on the server, and the router's first
|
|
58
|
+
navigation runs on a frame and awaits its route. `renderToString` serializes before that settles, so it
|
|
59
|
+
serves the shell with an empty `[view]` outlet for the client to fill; `renderToStringAsync` waits, and
|
|
60
|
+
serves the route the request's `location` names. `renderToString` **refuses** an `async
|
|
61
|
+
connectedCallback` rather than serve its empty markup.
|
|
62
|
+
|
|
63
|
+
**Renders take turns** — one at a time, across both entry points. The per-render bookkeeping is
|
|
64
|
+
module-level, so two renders interleaving would read each other's; queueing is the version that
|
|
65
|
+
cannot be wrong, costs one microtask when nothing is in flight, and is invisible because every caller
|
|
66
|
+
already awaits. A render that throws does not stop the queue.
|
|
67
|
+
|
|
68
|
+
## Options
|
|
69
|
+
|
|
70
|
+
| Option | |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `tag` | which element to render when the module defines several. Otherwise the module's exported class is matched against the registry — so **export the class**, or pass `tag` |
|
|
73
|
+
| `attributes` | the entry tag's attributes. **An object** — values escaped, names checked. A string is written through untouched (a sink: see [Security](#security)) |
|
|
74
|
+
| `props` | properties assigned to the instance before `connectedCallback`, by identity. A `__proto__` key is skipped, and a read-only property is refused by name |
|
|
75
|
+
| `children` | markup placed inside the entry tag, where a client parser would have put it — what a `<slot>` renders. **Raw markup** |
|
|
76
|
+
| `location` | this request's URL — a path or a full URL — applied for the render and restored after |
|
|
77
|
+
| `seen` | a `Set` carried across renders, so a page of islands ships each component's styles once |
|
|
78
|
+
| `base` | a directory the module URL must resolve inside. Pass it whenever **any part of the URL came from a request** |
|
|
79
|
+
| `static` | `true` for a page that will not be interactive: reactivity is skipped, about 3x faster, identical markup |
|
|
80
|
+
| `timeout` | how long `renderToStringAsync` waits on promises a component starts, in milliseconds (default 2000), before serving what it has and warning — see below. **`0` waits for nothing** (it is not "no limit", which this option cannot express): every such promise is abandoned at once |
|
|
81
|
+
|
|
82
|
+
A wrong type is refused with a `TypeError` naming the option (`children: 5` used to surface as
|
|
83
|
+
`markup.includes is not a function`).
|
|
84
|
+
|
|
85
|
+
**Pass `location`; never assign `globalThis.location` yourself.** The global belongs to the process
|
|
86
|
+
and a request does not: the call awaits `import()`, which yields on a module's first import, so
|
|
87
|
+
whichever request assigned last wins for every render after it. Measured with three concurrent
|
|
88
|
+
first-time imports, two of three rendered another request's path. The option is applied inside the
|
|
89
|
+
render's turn and restored in a `finally`. `title` is returned rather than left on the global for the
|
|
90
|
+
same reason, and the document's own title is restored afterwards. **Renders take turns**, process-wide: two
|
|
91
|
+
calls made together run one after the other, so no render ever sees another's frames, adopted stylesheets or
|
|
92
|
+
globals (measured: two `renderToStringAsync` calls started at once finish at 154 ms and 255 ms, the second's
|
|
93
|
+
budget starting at its turn).
|
|
94
|
+
|
|
95
|
+
**No render waits unboundedly on a component's promise.** `renderToStringAsync` awaits what a component starts
|
|
96
|
+
— an `async connectedCallback`, a promise a frame callback returns — for at most `timeout` milliseconds (2000 by
|
|
97
|
+
default) from the start of its turn. One that never settles, such as a wait on a child the server never defines,
|
|
98
|
+
used to hold the request open forever, and because renders take turns, every request after it as well. When the
|
|
99
|
+
budget runs out the render serves what it has and warns, in every build, naming the component — once per component
|
|
100
|
+
for the life of the process, as every ssr warning is: the page served is not the one its code describes, so raise
|
|
101
|
+
`timeout` if the wait is real or find the promise that never settles.
|
|
102
|
+
There is deliberately no way to wait without limit: `timeout: 0` means wait for nothing, and the largest value is
|
|
103
|
+
2147483647 ms.
|
|
104
|
+
|
|
105
|
+
**What ssr says, and how.** Every line ends with its code — the full explanation of a code is at
|
|
106
|
+
`https://verajs.dev/e/<code>` — and keeps its whole sentence in every build, since a server's log is read by its
|
|
107
|
+
developer. Two rules make it safe on a server: **a warning is said once per process per key** (the component, and the
|
|
108
|
+
attribute or event where that tells two facts apart), because a server renders per request and a per-render warning
|
|
109
|
+
would flood the log at request rate; and **text from outside — an error's message, a URL, a selector — is
|
|
110
|
+
JSON-quoted and cut to 80 characters**, so a newline or an escape sequence in it can neither forge nor hide a log line.
|
|
111
|
+
A refused `javascript:` URL is reported without its value at all, and data shaped like a template is reported and
|
|
112
|
+
rendered as the object it is. The errors the shim throws in the platform's own words (`Failed to execute 'appendChild'
|
|
113
|
+
on 'Node'…`) stay exactly those: this is a DOM, and it answers as the browser does.
|
|
114
|
+
|
|
115
|
+
**A wait on a child only the browser defines costs the whole `timeout`, on every request** — and since renders take
|
|
116
|
+
turns, every request queued behind it waits too. The warning names the component waiting and the child it waits on.
|
|
117
|
+
Don't make the setup wait for it — write the result into state when it arrives:
|
|
118
|
+
|
|
119
|
+
```js
|
|
120
|
+
connectedCallback() {
|
|
121
|
+
init({ host: this, shadow: 'open' }, () => {
|
|
122
|
+
const state = createStore({ ready: false });
|
|
123
|
+
customElements.whenDefined('x-map').then(() => (state.ready = true)); // not awaited: the server serves 'loading map'
|
|
124
|
+
return () => html`<p>${state.ready ? 'map ready' : 'loading map'}</p><x-map></x-map>`;
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
That serves the component's state from before the wait, which is exactly what the browser shows first, so hydrating
|
|
130
|
+
changes nothing — and it takes no time and prints no warning. Skipping only the `await`
|
|
131
|
+
(`if (!globalThis.__veraSsrShimmed) await …`) serves the state *after* it, which the browser then replaces with its own
|
|
132
|
+
starting state: a visible flash. A stand-in class defined on the server does the same.
|
|
133
|
+
|
|
134
|
+
**`globalThis.__veraSsrShimmed` is the supported way to tell the server render from a browser**, here and for guarding
|
|
135
|
+
client wiring: `@verajs/ssr` sets it to `true` when it is imported, before any component runs, and nothing sets it in a
|
|
136
|
+
browser. `typeof window` cannot tell them apart, because the server provides a `window`.
|
|
137
|
+
|
|
138
|
+
## What runs, and when
|
|
139
|
+
|
|
140
|
+
**The lifecycle runs the way it does in a browser.** The class is constructed through the registry,
|
|
141
|
+
the markup's attributes are set, `attributeChangedCallback` fires for each observed one on upgrade and
|
|
142
|
+
again on every later change, and then `connectedCallback` runs. `tests/lifecycle-parity.test.mjs`
|
|
143
|
+
renders each case on both sides and compares the DOM. What a component does to itself there — a
|
|
144
|
+
`setAttribute`, an `aria-*`, a class, a reflected property — reaches the markup.
|
|
145
|
+
|
|
146
|
+
**Frames are drained before the markup is read.** A server never paints, so `requestAnimationFrame`
|
|
147
|
+
(and `requestIdleCallback`) callbacks are queued and run once `connectedCallback` returns, then again
|
|
148
|
+
for whatever those schedule — so a re-render and every `effect` land in the markup, coalesced
|
|
149
|
+
exactly as a browser coalesces them.
|
|
150
|
+
|
|
151
|
+
- **An endless animation loop is bounded**: 20 rounds, then the render ships. What the loop left
|
|
152
|
+
queued is dropped, never run inside the next component's render.
|
|
153
|
+
- **The async chain lets promises settle between rounds.** A frame that returns a promise is awaited,
|
|
154
|
+
whatever it awaits; work a frame starts without returning it is caught if it lands within three idle
|
|
155
|
+
microtask turns (measured: a chain four microtasks deep).
|
|
156
|
+
- **a `'layout'` effect runs on a microtask.** Through `renderToStringAsync` its state reaches the
|
|
157
|
+
markup, as on the client. Through `renderToString` it runs — a side effect inside one *happens* on the
|
|
158
|
+
server — but after the template was serialized, so state it settles is not in the markup: settle it
|
|
159
|
+
before `render()`, or use `renderToStringAsync`.
|
|
160
|
+
|
|
161
|
+
**A failure rejects the render — it is never markup.** In a browser, core isolates a hook's error so
|
|
162
|
+
one bad effect cannot take out its neighbors, because the next render can recover. There is no next
|
|
163
|
+
render here, so every failure — a throwing hook or `connectedCallback`, a `settle` handler that
|
|
164
|
+
throws — rejects the render, naming the component (and how many more failed), with the original
|
|
165
|
+
error as `cause`. Catch it to fall back to a client-rendered shell, as you would with React or Vue.
|
|
166
|
+
|
|
167
|
+
**A component's render owns its own range and nothing else**, as in a browser: content already in the
|
|
168
|
+
container stays before it, a node the component appends to its own root stays after it, and both
|
|
169
|
+
survive every re-render. So `children` reach a light-DOM component and are still there after it
|
|
170
|
+
renders.
|
|
171
|
+
|
|
172
|
+
## Nested components
|
|
173
|
+
|
|
174
|
+
After a component renders, its markup is scanned for tags the registry knows, and each is rendered in
|
|
175
|
+
place — **exactly where the browser creates an element the definition upgrades**, read by the same tag scanner
|
|
176
|
+
every template goes through. It respects quoted attribute values (a `>` is legal inside one), leaves comments,
|
|
177
|
+
raw text (`<script>`, `<style>`, `<textarea>`, `<title>`…) and `<template>` content alone, and renders nothing
|
|
178
|
+
inside `<svg>` or `<math>`, where a dashed tag is a foreign element no definition upgrades — except inside an
|
|
179
|
+
HTML integration point (`<svg><foreignObject>`, `<math><mtext>`…), or after a tag that breaks out of foreign
|
|
180
|
+
content (`<svg><p><my-comp>`), both of which the browser reads as HTML. A tag's name is the whole name the tokenizer
|
|
181
|
+
reads, so `<my-comp.x>` is another, unregistered element and is left exactly as written. After `<font color>` inside
|
|
182
|
+
`<svg>` (a breakout this scan does not track) a component is not rendered on the server, and renders on the client.
|
|
183
|
+
|
|
187
184
|
- **A component can build another component.** `document.createElement('my-comp')` constructs the
|
|
188
|
-
registered class
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
-
|
|
252
|
-
(
|
|
253
|
-
not
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
- **A
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
`
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
`
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
in
|
|
359
|
-
and
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
`
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
`
|
|
377
|
-
|
|
378
|
-
|
|
185
|
+
registered class — field initializers run, `instanceof` answers — and appending it renders **that
|
|
186
|
+
instance**, so everything the parent assigned (`kid.rows = data`) survives.
|
|
187
|
+
- **A property bound on a component tag is delivered**, not dropped: written (`<props-row .item=${row}>`)
|
|
188
|
+
or spread (`props({ item })`), the value reaches the instance the scan renders — by identity, before
|
|
189
|
+
its lifecycle, exactly where the `props` option puts the entry component's. The markup never carries
|
|
190
|
+
it (a property is not an attribute), so the child renders from the same data its client render will
|
|
191
|
+
get: that is the hydration contract. An **unregistered** dashed tag passes through untouched.
|
|
192
|
+
- Both ride on a marker attribute that crosses the string boundary and is removed before the page is
|
|
193
|
+
returned. **It only ever produces the component it was written for**: a copy of it on another tag is
|
|
194
|
+
ignored, and a copy on a second element of the same tag renders the instance once, not twice.
|
|
195
|
+
- **Nesting is capped at 256 levels, and the client has no such cap.** A component that renders itself
|
|
196
|
+
recurses without bound, which on a server is a hung request, so the render refuses past 256 and says
|
|
197
|
+
so. 256 sits *below* where the client breaks (about 340 levels before a `RangeError`, engine-
|
|
198
|
+
dependent), so the server still fails first, and with a sentence.
|
|
199
|
+
|
|
200
|
+
## Static pages
|
|
201
|
+
|
|
202
|
+
`static: true` renders a page that will not be interactive, **about 3x faster** — 16 µs against
|
|
203
|
+
42–50 µs for a component rendering twenty rows. A server render is one shot: the subscriptions a store
|
|
204
|
+
builds while it runs are never fired afterwards, so tracking every read to create them is the whole of
|
|
205
|
+
the cost. With `static` on, a store's property reads skip tracking.
|
|
206
|
+
|
|
207
|
+
- **The markup is identical**, and not on a chosen example: `tests/ssr-static-mode.test.mjs` renders
|
|
208
|
+
*every* fixture in the suite both ways and compares markup, styles and title. A mode that cannot
|
|
209
|
+
drift is why this is an option rather than a second renderer.
|
|
210
|
+
- **A store written during a static render throws**, naming the option, rather than serving markup
|
|
211
|
+
that reflects none of the writes. In both builds — a server runs the production build, so a
|
|
212
|
+
development-only guard would be missing from the only place it matters.
|
|
213
|
+
- It applies to the render, not to the process: a render queued behind a static one, and any store
|
|
214
|
+
written outside a render, are reactive as ever.
|
|
215
|
+
|
|
216
|
+
It is `@verajs/ssr`'s own `'store'` insert — core knows nothing about it.
|
|
217
|
+
|
|
218
|
+
## Security
|
|
219
|
+
|
|
220
|
+
**Escaping happens at the render boundary, always.** Every interpolated value in a template is
|
|
221
|
+
escaped as it is written; `<style>` and `<script>` content is written raw with its own end tag
|
|
222
|
+
neutralized (`<\/style`, `<\/script` — valid CSS and JavaScript, invisible to the tokenizer), because a
|
|
223
|
+
browser does not decode a character reference inside either: escaping there protects nothing and
|
|
224
|
+
corrupts the content (`.a > .b` used to serve as `.a > .b`, a selector matching nothing).
|
|
225
|
+
`<title>` and `<textarea>` decode references, so they keep ordinary escaping. **The same rule holds for content
|
|
226
|
+
a component writes through the server DOM**: `textContent`, `value`, `innerHTML` or a text node in any of those
|
|
227
|
+
elements is stored as text and written by its parent's rule, so data can never close the element it is in. **Raw is decided by where
|
|
228
|
+
the browser will parse the element, not by its name**: inside `<svg>` or `<math>` a `<style>` is an SVG or
|
|
229
|
+
MathML element whose content is markup, and `<noscript>` is markup to a browser with scripting off — so
|
|
230
|
+
inside any of them every value is escaped, and so is every value in a template rendered into one (an
|
|
231
|
+
`svg`/`mathml` template included, wherever it renders) — except inside an HTML integration point, which the
|
|
232
|
+
browser reads as HTML: SVG `<foreignObject>`, `<desc>` and `<title>`, MathML `<mi>`, `<mo>`, `<mn>`, `<ms>` and
|
|
233
|
+
`<mtext>`, and an `<annotation-xml>` whose `encoding` is HTML, each only in its own namespace and only when not
|
|
234
|
+
self-closed (`<math><mi><mglyph>` is MathML again) — and after a tag that ENDS foreign content, which the browser
|
|
235
|
+
reads as HTML again (`<svg><p>`, `<math><b>`, `</p>`; the standard's breakout list). Inside `<xmp>`, `<noembed>`, `<noframes>` and
|
|
236
|
+
`<plaintext>`, which the browser reads as text whole, nothing is raw either. **And a tag is read where the
|
|
237
|
+
browser's tokenizer reads one**: a tag's name is the whole run up to whitespace, `/` or `>` (`<script.x>` is an
|
|
238
|
+
unknown element, never a `<script>`), a `<` before anything but a letter is text, `<!x>` and `<?x>` are comments,
|
|
239
|
+
and a quote or `=` inside a name is part of the name.
|
|
240
|
+
|
|
241
|
+
**Two options are raw markup, on purpose: `children`, and the string form of `attributes`.** Both are
|
|
242
|
+
written through untouched — that is what they are for — so neither may carry anything from a request
|
|
243
|
+
unsanitized. Everything else is checked:
|
|
244
|
+
|
|
245
|
+
- **The object form of `attributes` cannot leave the tag or add a second attribute.** A name carrying
|
|
246
|
+
whitespace, a quote, `/`, `=` or `>` is refused — the set `setAttribute` refuses in a browser — and
|
|
247
|
+
every value is escaped. `false`, `null` and `undefined` omit the attribute; `true` writes it empty (`name=""`).
|
|
248
|
+
- **`.innerHTML` and `.textContent` render on the server**, so trusted markup bound the sanctioned way
|
|
249
|
+
(`<div .innerHTML=${markup}>`) is in the served page rather than filled in after hydration. It is made to behave
|
|
250
|
+
as an `innerHTML` assignment, not as parsed page markup: a `<script>` in it is served with an inert `type` (an
|
|
251
|
+
assignment never runs one), and a `<template shadowrootmode>` cannot attach a shadow root (an assignment never
|
|
252
|
+
does) — wherever the tokenizer reads a start tag, which the server finds with the same scanner it reads every
|
|
253
|
+
template with. Whatever the markup leaves open is closed before the element's own end tag, and an unfinished tag
|
|
254
|
+
at its end is dropped, as an assignment drops it, so it cannot reach the markup after it. On a `<style>`/`<script>` host the value is raw text with its end tag neutralized; on a
|
|
255
|
+
`<textarea>`, `<title>` or other text-only host, inside `<svg>`/`<math>`, and for any `.textContent`, it is
|
|
256
|
+
escaped text. A `<script .textContent=${code}>` host is the one code-execution door this opens, and it is the
|
|
257
|
+
author's: it runs on the served page as it runs on the client. `.innerText`, `.outerHTML` and `.outerText` stay
|
|
258
|
+
client-only — the server serves the element's template content.
|
|
259
|
+
- **Data shaped like a template is text.** A value renders as markup only when its strings came from a tagged
|
|
260
|
+
template literal; a `{"strings": [...]}` from `JSON.parse` — or a real template sent through JSON, or a
|
|
261
|
+
hand-built `html([markup])` — is served as `[object Object]`, as the client renders it, and never throws.
|
|
262
|
+
- **A `__proto__` key in `props` is skipped**, so handing the option a parsed request body cannot
|
|
263
|
+
replace the component's prototype.
|
|
264
|
+
- **Every bound attribute value is served double-quoted, whatever quoting the template used.** A value
|
|
265
|
+
shares its attribute with any statics and other holes around it — `title=pre${x}`, `title=${a}${b}`,
|
|
266
|
+
`title = ${x}`, single or double quotes — and the server writes that whole attribute once, the way the
|
|
267
|
+
client's `setAttribute` stores it, so nothing a value holds can end the attribute or start another.
|
|
268
|
+
A hole that is the whole value omits the attribute for `null` and `undefined`, as the client does; a
|
|
269
|
+
hole joined with statics contributes empty text.
|
|
270
|
+
- **A bound `javascript:` URL is never served.** A template value bound where a browser navigates
|
|
271
|
+
(`href`, `src`, `action`, `formaction`, `xlink:href`, `data`, and an SVG animation's `to`, `from`,
|
|
272
|
+
`by` and `values`, item by item) is dropped when it parses as a `javascript:` URL — judged on the attribute's whole value, statics and character references
|
|
273
|
+
included, as the browser will read it — and a bound `srcdoc` attribute is never served. The client
|
|
274
|
+
renderer refuses exactly the same values, so the two agree.
|
|
275
|
+
- **`base` contains the module URL.** `renderToString` executes the module it is given, and mapping
|
|
276
|
+
a route to a component file is the obvious way to use a server renderer — so pass `base` whenever
|
|
277
|
+
any part of the URL came from a request:
|
|
278
|
+
|
|
279
|
+
```js
|
|
280
|
+
renderToString(new URL(`${page}.js`, components), { base: components });
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Anything resolving outside it is refused. `new URL` applies `../` before `renderToString` sees the
|
|
284
|
+
string, so without this the traversal has already happened by the time the call is made. It is
|
|
285
|
+
opt-in because most calls name a constant, and a check that is always trivially satisfied stops
|
|
286
|
+
being read.
|
|
287
|
+
- **`styles` comes back escaped for a `<style>` element**, since that is where a page shell puts it.
|
|
288
|
+
- **A dynamic attribute *name* is refused** — by the server in every build, and by the client renderer in
|
|
289
|
+
development. `<b ${name}="x">`, `<p data-${k}="1">`, `<p ${k}-x>`: the parser reads a name before any
|
|
290
|
+
value exists, so no position can hold it. Both throw at the template's first use, and the message shows
|
|
291
|
+
the `@verajs/renderer/spread` rewrite — `${spread({ [`data-${k}`]: '1' })}` — which applies the refusals
|
|
292
|
+
a runtime name needs. The same holds for a value in TAG position (`<${x}>`, `<my-${x}>`), which names
|
|
293
|
+
`@verajs/renderer/tag` — a runtime tag name is a tag value from that entry. The server refuses in production too, so a production server render of such a
|
|
294
|
+
template throws even though the client's production build would not — render it once in development
|
|
295
|
+
and it never gets that far.
|
|
296
|
+
- **A template ending inside a tag is refused** (`<b title="${x}` with no `>`), and so is **a template rendered
|
|
297
|
+
inside a text-only element** (`<textarea>`, `<title>`, …): both on the server in every build, the first also by
|
|
298
|
+
the client renderer in development. The client's parser drops an unfinished tag whole, so nothing can match it,
|
|
299
|
+
and a template's markup inside a text-only element is the one way a value could close that element. Strings,
|
|
300
|
+
numbers and arrays of them render in a `<textarea>` as always.
|
|
301
|
+
|
|
302
|
+
## Styles
|
|
303
|
+
|
|
304
|
+
`@verajs/styles` is wired on import, because `static styles` are part of what a browser renders.
|
|
305
|
+
|
|
306
|
+
- **Shadow DOM:** markup cannot carry a constructed sheet, so a component's styles are serialized as
|
|
307
|
+
`<style data-vm-sheet="styles">` inside its template — plain strings first, then sheets, which is the
|
|
308
|
+
order the browser's cascade applies them in (adopted sheets win over a root's own `<style>`). When
|
|
309
|
+
every style is a sheet the client can adopt, it removes that copy, so the rules never apply twice.
|
|
310
|
+
- **Light DOM:** a component's `@scope (tag) { … }` block is returned in `styles` for the page shell,
|
|
311
|
+
**only for the components this render touched**, and — with a shared `seen` — once across a page of
|
|
312
|
+
islands.
|
|
313
|
+
- **A tag's CSS is established once per process**: whichever render reaches it first sets it. That is
|
|
314
|
+
what stops a per-class sheet being emitted once per instance; the consequence is that CSS varying
|
|
315
|
+
per request is dropped, with a warning — once, naming the component. Put what varies in
|
|
316
|
+
custom properties (see the `@verajs/styles` README).
|
|
317
|
+
|
|
318
|
+
## The server DOM
|
|
319
|
+
|
|
320
|
+
Importing `@verajs/ssr` installs a DOM on `globalThis`: `document`, `window`, `customElements`,
|
|
321
|
+
`HTMLElement` and the rest, **replacing** any already there.
|
|
322
|
+
|
|
323
|
+
- **Import it first**, before anything that imports `@verajs/renderer`, which builds `TreeWalker`s at
|
|
324
|
+
import time and throws against a bare Node global. Core, `@verajs/styles` and `@verajs/router` are
|
|
325
|
+
order-independent.
|
|
326
|
+
- **Run any other DOM in another process.** jsdom in a test loses its globals the
|
|
327
|
+
moment this module loads, however late, and a component defined afterwards is never upgraded — with
|
|
328
|
+
nothing saying why. This repository's own tests render the server half in a subprocess for exactly
|
|
329
|
+
this reason.
|
|
330
|
+
- **A process that has loaded `@verajs/ssr` is a server.** Wiring vera's renderer there —
|
|
331
|
+
`wire([renderer])` or `wire([renderer({ shadow: 'open' })])` in app code the server and the browser
|
|
332
|
+
share — declines its render insert (the server renders with its own) and keeps only the shadow default,
|
|
333
|
+
so one shared wire call gives both sides the same default root; development says so once per process.
|
|
334
|
+
Import `@verajs/ssr` before that wire call. Code that needs the client renderer in the same process (a
|
|
335
|
+
test that server-renders and then hydrates) installs a client DOM and calls `renderInto` directly —
|
|
336
|
+
`wire([renderer])` there registers no client render insert — or renders the server half in a separate
|
|
337
|
+
process. The client renderer cannot draw into this DOM itself: it holds strings, not a tree. A renderer that is not vera's would displace the server's and is refused at render time; guard
|
|
338
|
+
its wiring (`if (!globalThis.__veraSsrShimmed)`).
|
|
339
|
+
|
|
340
|
+
**It is complete, and checked twice.** Every member a real element, shadow root, document,
|
|
341
|
+
`CSSStyleSheet`, `DOMTokenList` or window exposes in Chromium, Firefox and WebKit is either
|
|
342
|
+
implemented or listed as out of scope with a reason — and every implemented member is compared against
|
|
343
|
+
a real DOM, so one that exists and answers differently fails too. That second check found `tabIndex`
|
|
344
|
+
defaulting to 0, `draggable` defaulting to true, `role` answering `''` where the platform answers
|
|
345
|
+
`null`, `textContent = null` writing the word "null", and a closed shadow root handed straight back. It
|
|
346
|
+
compares a member's *shape*, not its answer to every input, so it is a net rather than a proof — three
|
|
347
|
+
classes of defect were found by going around it deliberately. The window's ~700 interface constructors
|
|
348
|
+
are covered by a rule rather than a list (every interface this DOM implements is exposed, so
|
|
349
|
+
`instanceof` answers for anything it hands you); `tests/dom-surface.mjs` holds the list, with no
|
|
350
|
+
dependency involved.
|
|
351
|
+
|
|
352
|
+
- **Element-specific properties reach the markup.** `input.disabled`, `a.href`, `td.colSpan`,
|
|
353
|
+
`option.selected` — 273 of them across 44 tags, measured from the three engines
|
|
354
|
+
(`scripts/measure-element-reflections.mjs`), each tag getting exactly its own interface, so
|
|
355
|
+
`'disabled' in paragraph` stays `false`. Without this, `button.disabled = true` stored a plain
|
|
356
|
+
property and **served a button that was not disabled** until the bundle landed. A property is in the
|
|
357
|
+
table only when all three engines agree and reading the attribute back gives what was written, which
|
|
358
|
+
excludes ones resolved against a document URL (`form.action`), read from layout (`input.width`) or
|
|
359
|
+
clamped (`meter.value`). `value`, `checked` and `selected` are mirrored to the markup deliberately:
|
|
360
|
+
a browser keeps them off it, but on a server the markup is the whole output.
|
|
361
|
+
- **Events are real and propagate** — capture, target and bubble phases, `once`, `handleEvent`
|
|
362
|
+
objects, `stopPropagation`, `stopImmediatePropagation`, `composedPath()`, a `dispatchEvent` return
|
|
363
|
+
reflecting `preventDefault`, and a shadow boundary crossed only by a `composed` event. The walk is
|
|
364
|
+
over the node tree, so an event does not continue into `document` or `window`.
|
|
365
|
+
- **Where the platform throws, this throws** — an attribute or tag name that cannot be written, a
|
|
366
|
+
second `attachShadow` or `attachInternals`, an invalid custom-element name, and every Node-typed
|
|
367
|
+
argument that is not a node (`appendChild({})`, `removeChild(null)`, `contains({})`), with the
|
|
368
|
+
platform's `TypeError`. `new HTMLElement()`, `new Node()` and `new X()` for a class never defined are
|
|
369
|
+
an `Illegal constructor`, as they are in a browser. Lenience on a server does not make anything work;
|
|
370
|
+
it moves the failure to the client and strips the context.
|
|
371
|
+
- **The Node interfaces are the platform's.** A text node is a `Node`, a `CharacterData` and a `Text`;
|
|
372
|
+
`Node`'s constants are on every node; `append({})` inserts the text `[object Object]`, as the
|
|
373
|
+
`(Node or DOMString)` union converts; and `String(node)` names its interface (`[object Text]`) — for
|
|
374
|
+
text, comments, fragments and shadow roots. An element's name depends on its tag and is not yet
|
|
375
|
+
answered (`[object Node]` here, `[object HTMLDivElement]` in a browser).
|
|
376
|
+
- **A selector this DOM cannot answer honestly throws** rather than answering `null`. It matches type,
|
|
377
|
+
class, id, every attribute operator, `:not()` and all four combinators — descendant, `>`, `+` and
|
|
378
|
+
`~`. Everything else raises, for **two different reasons**: `:hover`, `:checked`, `:visible` and
|
|
379
|
+
`:root` need user state, layout or a document a server does not have, while `:first-child`,
|
|
380
|
+
`:nth-child()`, `:empty`, `:first-of-type`, `:is()` and `:has()` are answerable here and simply are
|
|
381
|
+
not implemented.
|
|
382
|
+
- **Names fold as the platform folds them**: an HTML element lower-cases its tag and attribute names,
|
|
383
|
+
so an `attributes` entry spelled `User-ID` matches an `observedAttributes` entry `user-id`; an
|
|
384
|
+
element from `createElementNS` outside the HTML namespace keeps its case, so an SVG `viewBox`
|
|
385
|
+
survives.
|
|
386
|
+
- `attachShadow({ mode: 'closed' })` gives `element.shadowRoot === null`, as in a browser, and the root
|
|
387
|
+
is serialized anyway — declarative shadow DOM expresses `closed`. `attachInternals()` works, so a
|
|
388
|
+
form-associated custom element runs.
|
|
389
|
+
- The globals a component reaches for exist: `matchMedia` (matching nothing), `getComputedStyle`
|
|
390
|
+
(empty, as a detached element answers), `IntersectionObserver`, `ResizeObserver`,
|
|
391
|
+
`MutationObserver` and `PerformanceObserver` (inert, but constructing one does not throw).
|
|
392
|
+
- **`localStorage`, `sessionStorage`, `indexedDB` and `caches` are deliberately absent.** They are one
|
|
393
|
+
browser's state; a server that invented an empty one would render a logged-out shell the client
|
|
394
|
+
immediately replaces, with nothing failing anywhere. `typeof localStorage === 'undefined'` is the
|
|
395
|
+
guard the ecosystem already writes, and it only works if this does not lie.
|
|
396
|
+
|
|
397
|
+
**Where it deliberately differs:**
|
|
398
|
+
|
|
399
|
+
- **A collection is a plain array**, not a live `NodeList` — `childNodes`, `children`,
|
|
400
|
+
`querySelectorAll`, the `getElementsBy*` family. There is nothing to be live over in a single pass;
|
|
401
|
+
`item()` and `namedItem()` are provided anyway.
|
|
402
|
+
- **A parsed `<template>`'s content is opaque**, and `template.content` is `undefined`. The element is
|
|
403
|
+
modeled — queried, styled, serialized byte for byte — and a query on the host correctly does not
|
|
404
|
+
descend into it; reaching *into* one is what is missing.
|
|
405
|
+
- **A constructed sheet holds its CSS as text**, so `cssRules` is empty and `deleteRule` refuses
|
|
406
|
+
rather than pretends. `checkVisibility()` is always `false` and layout reads as zero, as for a
|
|
407
|
+
detached element in a browser. A `style` value is kept as written (`url("data:…")` keeps its quotes).
|
|
408
|
+
- `insertAdjacentHTML` with `beforebegin` or `afterend` raises a message explaining that a
|
|
409
|
+
server-rendered component has no parent.
|
|
410
|
+
- **A created or parsed `<pre>`, `<listing>` or `<textarea>` whose text begins with a line feed reads back with
|
|
411
|
+
one extra line feed from `innerHTML`/`outerHTML`.** The parser takes one line feed right after those start tags,
|
|
412
|
+
and a browser's own serialization does not account for it — Chromium, Firefox and WebKit serialize the text
|
|
413
|
+
`"\nabc"` as `<pre>\nabc</pre>`, which parses back as `"abc"`. This DOM's serialization is what the server sends,
|
|
414
|
+
so it writes the one the parser will take; templates and `.textContent`/`.value`/`.innerHTML` bindings do the same.
|
|
415
|
+
|
|
416
|
+
**Values read back are the platform's.** A parsed node's text, attribute and comment values are what a browser's
|
|
417
|
+
parser makes of the markup: line breaks normalized (CRLF and CR read as LF; a ` ` reference stays a CR),
|
|
418
|
+
`<textarea>` and `<title>` content decoded, and the line feed after `<pre>`/`<listing>`/`<textarea>` taken. The
|
|
419
|
+
markup itself is served byte for byte as it was written.
|
|
420
|
+
|
|
421
|
+
## What cannot round-trip
|
|
422
|
+
|
|
423
|
+
- **A binding inside a nested `<template>`'s content is ignored, on the server and the client alike.**
|
|
424
|
+
That content is inert markup the renderer never walks, so a value there is never rendered and an
|
|
425
|
+
attribute holding one is dropped whole; a binding on the `<template>` element itself is ordinary.
|
|
426
|
+
Render into the live tree instead.
|
|
427
|
+
- **A `<select>`'s value is served as `<option selected>`** — assigning the property *selects an
|
|
428
|
+
option*, so that is all markup can say, and `.selectedIndex` is served the same way by position. Matching follows the platform (the `value` attribute
|
|
429
|
+
verbatim, otherwise the option's text stripped and collapsed; first match wins), asserted against
|
|
430
|
+
Chromium, Firefox and WebKit in `tests/browser/select-value.test.js`. But a value matching no option cannot be served:
|
|
431
|
+
the client leaves nothing selected, while a parsed `<select>` with no `selected` option shows its
|
|
432
|
+
first, and there is no markup for "none of them". An index out of range, `-1` included, is the same case.
|
|
433
|
+
- **A carriage return survives, as ` `** — the HTML parser collapses a raw CR before tokenizing,
|
|
434
|
+
so escaping it is what keeps a `<textarea>` value or a CSV cell identical on both sides.
|
|
435
|
+
**RAWTEXT is the exception, and it is not fixable**: inside `<style>` and `<script>` a reference is
|
|
436
|
+
not decoded, so there is no spelling of a CR that survives there. CR and LF are interchangeable
|
|
437
|
+
whitespace to CSS and JavaScript, so nothing renders wrongly — the two sides simply hold different
|
|
438
|
+
strings. Asserted in `tests/browser/rawtext-carriage-return.test.js`.
|
|
439
|
+
- **A `<style>` or `<script>` the server cannot place in HTML is served escaped.** Raw text is recognized
|
|
440
|
+
outside `<svg>`, `<math>` and `<noscript>`, inside their HTML integration points (`<svg><foreignObject>`,
|
|
441
|
+
`<math><mi>`…) and after a breakout tag (`<svg><p>`), but the scanner does not track the remaining ways a browser
|
|
442
|
+
re-enters HTML: `<font>` with a `color`, `face` or `size` attribute (it breaks out; here it never does), an end tag
|
|
443
|
+
the parser ignores, an `svg` template rendered outside any `<svg>`, and a template rendered INTO a foreign position
|
|
444
|
+
by its parent — it knows the depth it starts at, not whether that is
|
|
445
|
+
SVG or MathML, so it recognizes no integration point (`html`<svg>${svg`<foreignObject><style>…`}</svg>``). There
|
|
446
|
+
the browser reads HTML raw text, so a `>` in the stylesheet arrives as `>` until hydration replaces it. That is
|
|
447
|
+
the safe direction of a misreading on purpose: the other one writes a value's markup into the page. Put the
|
|
448
|
+
stylesheet in the template that opens the foreign element, or outside it.
|
|
449
|
+
- **`.innerHTML` markup is parsed in place on the server and as a fragment on the client.** The client parses
|
|
450
|
+
the value with the element as its context; the served page is parsed with every real ancestor around it, so a
|
|
451
|
+
few shapes nest differently on first paint — a `<p>` inside a `<p .innerHTML>` (the page closes the outer one),
|
|
452
|
+
an `<a>` inside an `<a>`, table parts outside a table. Hydration re-assigns the value, so the client's DOM is
|
|
453
|
+
right once the script runs; an inline handler in the markup (`onload`, `onerror`) therefore fires twice on an SSR
|
|
454
|
+
page, once from the served HTML and once from the assignment. Inside `<svg>`/`<math>` the server writes the
|
|
455
|
+
value as escaped text, the safe side of the same misreading, until hydration assigns it.
|
|
456
|
+
- **An ordinary element a template leaves open nests differently.** The client parses each template on its own
|
|
457
|
+
and closes what it left open at its end; the server concatenates. Whatever changes how the rest of the page
|
|
458
|
+
PARSES is closed at the template's end on the server too — a comment, `<style>`/`<script>`, `<textarea>` and the
|
|
459
|
+
other text-only elements, `<svg>`, `<math>`, `<noscript>`, `<template>` — so a child can never reach its
|
|
460
|
+
parent's markup. A plain `<b>` or `<div>` left open is not closed, so the parent's next markup nests inside it
|
|
461
|
+
on the server and beside it on the client. Close every element inside the template that opens it.
|
|
462
|
+
- **Beyond that, three things cannot survive a server round trip, and are the only three**: that carriage return
|
|
463
|
+
inside `<style>`/`<script>`, and two characters. **NUL** is dropped in text and becomes U+FFFD in an
|
|
464
|
+
attribute or RAWTEXT, and no spelling round-trips, so it is left alone rather than silently
|
|
465
|
+
rewritten. **A lone surrogate** is not encodable in UTF-8, so the *transport* replaces it. Both are
|
|
466
|
+
covered by `tests/ssr-text-boundary.test.mjs`, alongside twenty-odd cases that do round-trip exactly.
|
|
467
|
+
|
|
468
|
+
## Known limits
|
|
469
|
+
|
|
470
|
+
- **A parsed node decodes six named references**: `&`, `<`, `>`, `"`, `'` and ` `, and
|
|
471
|
+
every numeric one. Any other (`©`, `—`, a legacy `&` with no `;`) reads back as written in that node's
|
|
472
|
+
`textContent` and attributes. The markup is served unchanged, so the page is right; only what a server component
|
|
473
|
+
READS from such markup differs.
|
|
474
|
+
|
|
475
|
+
- `keyed()` and `hold()` are client-renderer constructs; templates that must also server-render use
|
|
476
|
+
plain `.map`.
|
|
477
|
+
- **`slotAssignment: 'manual'` cannot be server-rendered**: declarative shadow DOM has no form for it,
|
|
478
|
+
and `attachShadow` ignores its options when it reuses a declarative root, so the client cannot
|
|
479
|
+
repair it. `mode`, `delegatesFocus`, `clonable` and `serializable` are all serialized.
|
|
379
480
|
- A function interpolated at a text position renders as nothing here and as its source on the
|
|
380
481
|
client — put functions in `@event` bindings, where both sides drop them.
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
482
|
+
- **A hole right after a raw-text element's whole end-tag name (`<style>a</style${x}`) is refused here** as a
|
|
483
|
+
tag-name hole (as core's renderer refuses it in development), while `@verajs/lite`, `@verajs/static` and core in
|
|
484
|
+
production render it (the closer the value completes cannot end the element). Every shorter split (`</sty${x}`)
|
|
485
|
+
renders everywhere. Safe both ways; such CSS is rare.
|
|
486
|
+
- **A `@verajs/lite` component whose raw text holds something that only LOOKS like an end tag** (`<style>p{}</stylex>`,
|
|
487
|
+
`</style\v`) is refused on the server (`tier-hole-position`): lite parses its template with this DOM, which declines
|
|
488
|
+
markup it cannot reproduce exactly. Core's components serve it, written as every side writes a style's text
|
|
489
|
+
(`<\/stylex`). Safe; such text is rare.
|
|
490
|
+
- **A template in an HTML `<title>` or `<textarea>` is refused here** (`ssr-template-in-text`), while core's renderer
|
|
491
|
+
places it and warns in development that it is never shown there. Such a template is a mistake either way, and this
|
|
492
|
+
server cannot write elements a browser would keep there: it reads that content back as text. Render a string.
|
|
493
|
+
- **A value inside `<iframe>`, `<noscript>` or an obsolete raw-text element is served escaped as text**, while core's
|
|
494
|
+
renderer writes it fully encoded (every ASCII non-word character as a character reference), so the bytes differ and
|
|
495
|
+
hydration rewrites that text. Both are inert after a save and reload; a template inside a `<noscript>` is refused
|
|
496
|
+
here as one inside a text-only element is.
|
|
497
|
+
- **What a render creates leaves every store when its render ends.** Its components are reactive DURING the render
|
|
498
|
+
(a write in a setup or a router's first navigation re-renders before the markup is written), and nothing they read
|
|
499
|
+
keeps them alive afterwards. Module-scope state — a store, a `computed` — belongs to the process and stays live; a
|
|
500
|
+
`computed` made inside a render and kept beyond it (stored on a module) stops updating when that render ends. Client
|
|
501
|
+
code in the same process created while an async render is awaiting is treated as part of that render.
|
|
502
|
+
- **No streaming.** `renderToString` returns a string where `@lit-labs/ssr` yields a stream. That buys
|
|
503
|
+
time-to-first-byte in proportion to how long a render takes, and a 100-row table here is PERF_TABLE µs
|
|
504
|
+
— the response is built before a stream would flush its first chunk. Worth revisiting for a page big
|
|
505
|
+
enough that it stops being true.
|
|
506
|
+
|
|
507
|
+
## Performance
|
|
508
|
+
|
|
509
|
+
`node bench/ssr.mjs` (fastest of 7 rotated rounds; run `cd bench && npm install` first), µs per render
|
|
510
|
+
— a small component, and a 100-row table:
|
|
511
|
+
|
|
512
|
+
| | small | table |
|
|
513
|
+
| --- | --- | --- |
|
|
514
|
+
| **template serialization** — `serializeTemplate` vs `@lit-labs/ssr` | **PERF** | **PERF** |
|
|
515
|
+
| | lit PERF | lit PERF |
|
|
516
|
+
| **whole component** — `renderToString` vs a real `LitElement` | **PERF** | **PERF** |
|
|
517
|
+
| | lit PERF | lit PERF |
|
|
518
|
+
|
|
519
|
+
Vue's compiled SSR is PERF / PERF µs and React PERF / PERF µs, neither of which renders a component.
|
|
520
|
+
The lit element row runs in a separate process: `@lit-labs/ssr` and this package both install DOM
|
|
521
|
+
globals and cannot share one.
|
|
384
522
|
|
|
385
523
|
## Also exported
|
|
386
524
|
|
|
387
|
-
`registry`
|
|
388
|
-
`serializeTemplate
|
|
389
|
-
|
|
390
|
-
`renderToString` / `renderToStringAsync`; these are listed so their presence is a decision rather
|
|
391
|
-
than an accident.
|
|
525
|
+
`registry` — the `Map` of tag → class this process has seen through `customElements.define` — and
|
|
526
|
+
`serializeTemplate`, the sigil-aware template flattener (one template to markup, no component scan),
|
|
527
|
+
are the two seams an advanced integration reaches for: a custom scanner, a fixture builder.
|
|
392
528
|
|
|
393
529
|
```js
|
|
394
|
-
import {
|
|
395
|
-
|
|
396
|
-
const
|
|
397
|
-
const page = await renderToStringAsync(entry); // same signature, awaits async lifecycles
|
|
398
|
-
|
|
399
|
-
registry.has('app-shell'); // true once the component module has run
|
|
400
|
-
const fragment = serializeTemplate(html`<p>${x}</p>`); // one template to markup, no component scan
|
|
530
|
+
import { registry, serializeTemplate } from '@verajs/ssr';
|
|
531
|
+
registry.has('app-shell'); // true once the component's module has run
|
|
532
|
+
const fragment = serializeTemplate(html`<p>${x}</p>`); // '<p>…</p>', every value escaped
|
|
401
533
|
```
|
|
402
534
|
|
|
403
535
|
## For AI assistants — and anyone who wants the whole API on one page
|