Text Node Hydration Conventions
When building interactive selective islands in Drift Static, understanding how Server-Side Rendered (SSR) HTML interacts with browser DOM parsers is essential for seamless client-side hydration.
The Browser Text Node Coalescing Phenomenon
During SSR, Drift serializes your component's template into standard HTML text. When the browser loads this HTML, the browser's native HTML parser constructs the DOM tree.
According to the HTML5 specification, when the browser HTML parser encounters contiguous character data inside an element, it collapses them into a single DOM TextNode, regardless of how many template interpolations originally generated the text.
Why Hydration Desynchronization Occurs
Consider a button that mixes adjacent static text with a dynamic variable:
<!-- Anti-pattern in current versions -->
<button class="btn" onclick={decrement}>- {step}</button>
Here is how the compiler and runtime process this element:
- AOT Bytecode Emission: The compiler generates two separate bytecode instructions:
CREATE_TEXTfor the static string"- "INTERPOLATE_TEXTfor the dynamic value of{step}
- SSR HTML Serialization: The server emits
<button class="btn">- 1</button>. - Browser DOM Construction: The browser parses this into
<button class="btn">containing one single TextNode with value"- 1". - Hydration Cursor Step: During client hydration, Drift's
HydrationCursorwalks the DOM using a browserTreeWalker:CREATE_TEXTclaims the singleTextNode("- 1").INTERPOLATE_TEXTexecutes next and expects a second text node. Finding none inside the button, theTreeWalkerlooks ahead into the next sibling element (e.g. the adjacent button) and claims its text node instead.- This shifts the cursor forward by one node. Subsequent elements, registers, and event listeners (
onclick) become bound to the wrong DOM nodes.
Recommended Patterns and Solutions
To maintain 1-to-1 parity between bytecode text instructions and DOM text nodes during hydration, use one of the following three patterns:
Pattern A: Derived Computed Label (Recommended)
Compute the label as a single reactive derived variable:
<script>
let count = 0;
let step = 1;
const decLabel = derive(() => '- ' + step);
const incLabel = derive(() => '+ ' + step);
function decrement() {
count = count - step;
}
</script>
<button class="btn" onclick={decrement}>{decLabel}</button>
- Why it works: Exactly one
INTERPOLATE_TEXTinstruction is emitted, matching the single DOMTextNodeparsed by the browser.
Pattern B: Template Expression Concatenation
Combine the static prefix and dynamic state inside a single interpolation:
<button class="btn" onclick={decrement}>{'- ' + step}</button>
- Why it works: The compiler evaluates the entire expression in a single
INTERPOLATE_TEXTinstruction, creating exactly one text node.
Pattern C: Separate Child Element Tags
If you need distinct semantic or styling hooks, separate the static and dynamic text into their own element tags:
<button class="btn" onclick={decrement}>
<span class="btn-prefix">-</span>
<span class="btn-value">{step}</span>
</button>
- Why it works: Each text node is enclosed in its own DOM element, preventing the browser HTML parser from collapsing them into one.
Future Roadmap Note
Current Version Note: This authoring convention applies as of now only in current DriftJS versions (v0.0.x).
Future versions of the DriftJS compiler and SSR serializer are planned to handle this automatically:
- Automatic Compile-Time Text Coalescing: The AOT transformer will automatically fuse adjacent static text and interpolations into a single concatenated expression during compilation.
- SSR Boundary Delimiters: The SSR serializer may insert lightweight comment delimiters (
<!-- -->) between adjacent text nodes to instruct the browser parser not to merge them.Until these automated compiler features are released in an upcoming version, adopting the derived label or single-expression pattern ensures reliable hydration.