@doars/staark-isomorphic
v1.6.10
Published
A server side rendering library for staark.
Readme
staark isomorphic
A server side rendering library for staark. It provides methods to convert a staark abstract node tree into a string, making it excellent for server-side rendering (SSR) and static site generation (SSG).
You have two primary functions at your disposal stringify and stringifyFull. These functions allow the application state and abstract node tree to be rendered to strings. Let’s walk through how each of these functions can be used effectively.
The stringify function is your gateway to converting your application’s view into a static HTML string. This is particularly useful for generating the initial HTML on the server before sending it to the client. It takes in two parameters a view function that takes in the state and outputs the abstract node tree, and optionally an initial state object that your application starts with. When you call stringify, it returns an array with two elements, firstly the rendered HTML as a string, as well as the abstract node tree.
import { node as n, stringify } from '@doars/staark-isomorphic'
const [html, tree] = stringify(
(state) => n('div', [
n('span', state.count),
n('button', {
click: () => state.count++,
}, 'add')
]),
{ count: 0 },
)
console.log(html) // '<div><span>0</span><button>add</button></div>'
console.log(tree) // [...]The stringifyFull function goes a step further by not only rendering your view to a static HTML string but also serializing the abstract node tree and the entire application state. This is particularly useful when you need to transfer the initial state and abstract node structure from server to client. It takes in two parameters a view function that takes in the state and outputs the abstract node tree, and optionally an initial state object that your application starts with. When you call stringifyFull, it returns an array with three elements, firstly the rendered HTML as a string, as well as the serialized abstract node tree, and finally the serialized initial state.
import { node as n, stringifyFull } from '@doars/staark-isomorphic'
const [html, tree, state] = stringifyFull(
(state) => n('div', [
n('span', state.count),
n('button', {
click: () => state.count++,
}, 'add')
]),
{ count: 0 },
)
console.log(html) // '<div><span>0</span><button>add</button></div>'
console.log(tree) // '[...]'
console.log(state) // '{"count":0}'The added benefit of stringifying the abstract node tree and state is that both can be passed to staark for hydration alongside the rendered HTML.
<body>
<div id="app">
<div><span>0</span><button>add</button></div>
</div>
<script type="module">
import { mount, node as n } from '@doars/staark'
const stringifiedTree = '[...]'
const stringifiedState = '{"count":0}'
mount(
document.body.querySelector('#app'),
(state) => n('div', [
n('span', state.count),
n('button', {
click: () => state.count++,
}, 'add')
]),
stringifiedState,
stringifiedTree,
)
</script>
</body>If you don't care about the state because you might be using your own state solution then you'll only need the rendered abstract node tree. Well there are two functions specially made for this, the stringifyPatch and stringifyPatchFull functions. The difference between these and the previous two are that the first parameter is the abstract node tree that would be returned by the render function and that there is no second parameter for providing the state.
import { node as n, stringifyPatch } from '@doars/staark-isomorphic'
const [html, tree] = stringifyPatch(
n('div', [
n('p', 'Hello there'),
n('p', 'General Kenobi'),
]),
)
console.log(html) // '<div><p>Hello there</p><p>General Kenobi</p></div>'
console.log(tree) // [...]And of course the stringifyPatchFull function will render not just the abstract node tree but stringify it as well.
import { node as n, stringifyPatchFull } from '@doars/staark-isomorphic'
const [html, tree] = stringifyPatchFull(
n('div', [
n('p', 'Hello there'),
n('p', 'General Kenobi'),
]),
)
console.log(html) // '<div><p>Hello there</p><p>General Kenobi</p></div>'
console.log(tree) // '[...]'As mentioned before, the output of stringifyPatchFull is ideal for hydration with staark-patch.
<body>
<div id="app">
<div><p>Hello there</p><p>General Kenobi</p></div>
</div>
<script type="module">
import { node as n, prepare } from '@doars/staark-patch'
const stringifiedTree = '[...]'
const patch = prepare(
document.body.querySelector('#app'),
stringifiedTree,
)
patch(
n('div', [
n('p', 'Hello there'),
n('p', 'General Kenobi'),
]),
)
</script>
</body>The library also exports conditional, factory, fctory, identifier, match, memo, nde, and node, so they do not have to be imported from Staark separately. Do note that stringifyPatch and stringifyPatchFull cannot render a memo node meaningfully because there is no state to provide to its render function.
Text and attribute values are HTML-escaped, unsafe element and attribute names are rejected, and function-valued attributes are not written to HTML. State is serialized with JSON.stringify, so it must satisfy the normal JSON serialization constraints. When transporting serialized state and trees to the browser, do not interpolate arbitrary values directly into an inline script; use the safe encoding or data transport provided by your server framework.
Rendering benchmark
Run npm run benchmark --workspace=packages/staark-isomorphic to compare the published concatenation renderer with the private fragment-array experiment. The fixtures cover broad and deep trees, attribute-heavy nodes, escaping, SVG, custom elements, boolean attributes, classes, styles, and memo output. Exact numbers depend on the runtime and machine, so run the benchmark in your target environment when making implementation decisions.
Installation
Via NPM
npm install @doars/staark-isomorphicIIFE build via a CDN
<!-- Bundle -->
<script src="https://cdn.jsdelivr.net/npm/@doars/staark-isomorphic@1/dst/staark-isomorphic.iife.js"></script>
<!-- Bundle minified -->
<script src="https://cdn.jsdelivr.net/npm/@doars/staark-isomorphic@1/dst/staark-isomorphic.iife.min.js"></script>ESM build via a CDN
// Bundle.
import { stringify } from 'https://cdn.jsdelivr.net/npm/@doars/staark-isomorphic@1/dst/staark-isomorphic.js'
// Bundle minified.
import { stringify } from 'https://cdn.jsdelivr.net/npm/@doars/staark-isomorphic@1/dst/staark-isomorphic.min.js'For compact language-model documentation, see llms.txt.