Arrow keys: ← previous · → next 37 of 37
@nodedk/render
0.1.2 stable isomorphic

render#

HTML rendering with conditionals, loops, data binding, components, slots, and pipes. Works on the server and in the browser.

Zero dependencies. Tiny footprint, only 6kb gzipped.

Use normal .html files, syntax is W3C standards compatible, no extra tooling required.

Install#

npm i @nodedk/render

Usage#

Compile once and reuse the function with different data:

var render = require('@nodedk/render')
var template = render.compile('<h1 text="title"></h1>')

var html = template({ title: 'Hello & welcome' })
// <h1>Hello &amp; welcome</h1>

Global data#

Pass shared variables through the data option when compiling:

var data = { site: { name: 'My site' } }
var template = render.compile('<h1 text="site.name"></h1>', { data })

template() // <h1>My site</h1>
// Render data overrides shared values
template({ site: { name: 'Another site' } }) // <h1>Another site</h1>
template({ site: null }) // <h1></h1>
template({ site: undefined }) // <h1></h1>

// Shared changes apply to later renders
data.site.name = 'Updated site'
template() // <h1>Updated site</h1>

Components use shared data unless overridden by props:

<template is="site-header">
  <h1 text="site.name"></h1>
</template>

<!-- Uses shared site.name -->
<site-header></site-header>
<!-- Pass render data explicitly to use it in a component -->
<site-header :site="site"></site-header>
<!-- Overrides shared site.name -->
<site-header :site="{name: 'Component site'}"></site-header>

Text and HTML#

text escapes values; raw inserts HTML unchanged:

<h1 text="title"></h1>
<!-- Tag forms leave no wrapper; null and undefined become empty text -->
<p>Hello <text value="user.name"></text>!</p>
<div raw="body"></div>
<raw value="body"></raw>

Attributes#

Prefix attributes with : to evaluate and escape their values:

<!-- Null and undefined omit the attribute -->
<a :href="url" text="label"></a>
<img :src="image.url" :alt="image.description">
<!-- Boolean attributes appear only when truthy -->
<button :disabled="busy">Save</button>
<div :class="active ? 'active' : 'idle'"></div>

Conditions and loops#

Use if for conditions, of for arrays, and in for objects:

<p if="available">In stock</p>
<p if="!available">Sold out</p>

<!-- Loop variables take precedence; for runs before if -->
<ul>
  <li for="item, index of items" if="item.visible">
    <text value="index"></text>: <text value="item.name"></text>
  </li>
</ul>

<div for="value, key in settings">
  <text value="key"></text>: <text value="value"></text>
</div>

Components and slots#

Define components at the top level; attributes pass strings and : passes data:

<template is="card">
  <article>
    <!-- Access props directly by name -->
    <h2 text="title"></h2>
    <!-- Fallback when no default slot is supplied -->
    <slot>Default body</slot>
    <footer><slot name="footer"></slot></footer>
  </article>
</template>

<card :title="product.name">
  <!-- Default slot: reads caller data, then shared defaults -->
  <p text="description"></p>
  <!-- Named slot: assign a direct child -->
  <button slot="footer">Buy</button>
</card>

Pass separate definitions through components:

var template = render.compile('<card :title="title"></card>', {
  components: [
    '<template is="card"><h2 text="title"></h2></template>'
  ]
})

Passing prop objects#

Pass an object with props (no : prefix):

<template is="card">
  <h2 text="title"></h2>
  <p text="description"></p>
</template>

<!-- Explicit attributes win in either order; product stays unchanged -->
<card props="product" title="Featured"></card>
<card title="Featured" props="product"></card>
<card props="{title: 'Featured', description: product.description}"></card>

Prop types#

Declare optional prop types on a component template:

<template is="card" name="string" age="number" active="boolean" data="object" items="array">
  <h2 text="name"></h2>
  <p text="age"></p>
</template>

<card name="Ada" age="42" active="true" data='{"id":1}' items="[2,3]"></card>
<!-- Explicit age wins, then converts to number 43 -->
<card props="{name: 'Ada', age: '42'}" :age="43"></card>
<!-- Missing or null props use defaults; objects and arrays get fresh defaults -->
<card></card>
Type Conversion Default
string JavaScript String(value) ''
number JavaScript Number(value); NaN falls back to 0 0
boolean JavaScript truthiness, except 'false' and '0' become false false
object Parse JSON strings; accept non-array objects Fresh {}
array Parse JSON strings; accept arrays Fresh []

Expressions#

Supported Syntax
Values Strings, decimal numbers, true, false, null, undefined
Arrays and objects [1, 2, 3], {name: user.name, labels: ['a', 'b'],}
Property access user.name, items[0], settings[key]
Arithmetic +, -, *, /, %, parentheses
Comparisons ==, !=, ===, !==, <, <=, >, >=
Logic !, &&, ||, ??, condition ? yes : no

Use expressions in bindings, including nested arrays and objects:

<template is="user-list">
  <ul if="settings.visible">
    <li for="user of users" text="user.name ?? 'Anonymous'"></li>
  </ul>
</template>

<user-list :settings="{visible: true}" :users="[{name: name}, {name: 'Grace'}]"></user-list>

Pipes#

Register functions as pipes; they run left to right with the value first:

var template = render.compile('<p text="title | truncate(limit) | uppercase"></p>', {
  pipes: {
    truncate: (value, length) => value.slice(0, length),
    uppercase: value => value.toUpperCase()
  }
})

template({ title: 'Hello world', limit: 5 })
// <p>HELLO</p>
<!-- Pipes have lowest precedence; use parentheses within expressions -->
<p text="compact ? (title | truncate(30)) : title"></p>
<!-- Use pipes instead of function or method calls -->
<p text="title | uppercase"></p>

Literal content#

. reads literal inner HTML without evaluating its directives:

<h2 text=". | truncate(30) | uppercase">Hello world</h2>
<!-- Displays the strong tags as text -->
<div text=".">Hello <strong>world</strong></div>
<!-- Preserves the strong tags as HTML -->
<div raw=".">Hello <strong>world</strong></div>

Benchmarks#

TL;DR: For the 1,000-item workload below, @nodedk/render renders approximately 75% faster than EJS, 85% faster than React, 136% faster than Handlebars, and 161% faster than Mustache, measured as renders per second.

Times are in microseconds (µs); lower is faster.

Engine Compile Render 10 items Render 100 items Render 1,000 items
@nodedk/render 11.21 3.12 29.01 283.61
EJS 11.65 5.36 49.23 495.52
React 326.90 6.38 51.69 524.24
Handlebars 120.25 7.54 67.88 669.18
Mustache 5.38 8.17 74.37 740.32

The bundle size is only 6kb gzipped including the compiler and parser.

Tests#

npm test

Created by Vidar Eldøy

Tools for business systems.