Looking to build interactive web apps with ultimate flexibility and adaptability?
Check out π mizu.js πβπ¦Ί!
It offers around thirty powerful directives to dynamically render HTML, listen to events, create custom elements, bind and model attributes, handle HTTP requests, render markdown and code, and much much more!
And it works client-side on any modern browser...
...but also server-side on your favorite runtime, whether it's Node, Deno, or Bun! You can even use it for static site generation!
Over the years, I've become increasingly frustrated with the need to set up an entire ecosystem just to create simple interactive web pages. You often need a dedicated toolbox, tons of dependencies, transpiling steps, and to learn a new superset of a language. You may even end up spending more time setting up your environment than actually working on your project! That's why I grew fond of libraries such as Alpine.js and htmx, which require no setup and are easy to use. However, I felt these had some limitations. Since they were mostly designed for client-side usage, it wasn't really possible to use them in server-side rendering contexts (including static generation). In the meantime, I started writing more and more isomorphic JavaScript (i.e., working both in client and server) and found Deno to be the perfect runtime for it. Deno relies on web standards rather than implementing its own like Node. Because of this, I encountered some compatibility issues, which shouldn't exist, as developers should be free to use whatever that suits them best, whether it's Node, Deno, Bun or the browser. With all these points in mind, I started working on Β« ζ°΄ Β» (mizu, the kanji for water in Japanese), a new library that attempt to addresses all the above-mentioned issues. And today, I'm excited to introduce it to you!Why yet another JavaScript templating library?
I get your concern, but hear me out!
mizu.js integrates directly with your HTML and uses vanilla JavaScript expressions for its expressions. This means you don't need to learn a new language or paradigm to start using it.
<!-- Conditionally render elements -->
<a *if="Math.round(Math.random())">Heads!<a>
<b *else>Tails!</b>
<!-- Render list elements dynamically -->
<ul>
<li *for="const value of ['foo', 'bar', 'baz']" *text="value"></li>
<li *for="['qux', 'quux', 'corge']" *text="$value"></li>
</ul>
<!-- Bind attributes and handle events -->
<form @submit.prevent :class="{ 'user-form': true }" *set="{ input: '' }">
<input type="text" ::value="input">
</form>
<!-- Template text content -->
<span *text="`Today is ${new Date()}`"></span>
<span *mustache>Today is {{ new Date() }}</span>
In mizu.js, the first character of a directive indicates its purpose:
-
*for general directives -
@for event-based directives -
:for attribute binding directives-
::for two-way binding directives (also known as modeling)
-
You might notice some similarities with the syntax from other frameworks and libraries, which is intentional.
mizu.js is reactive, automatically updating the DOM whenever your data changes (on the client-side).
Rendering rich content
mizu.js also offers some neat directives to easily render rich content such as markdown or code syntax highlighting.
<!-- Automatically generate a table of contents from h1-h6 tags within the selected element -->
<nav *toc="'main section'"></nav>
<!-- Render markdown content -->
<div *markdown>**hello world!**</div>
<!-- Highlight syntax using TypeScript flavor -->
<code *code[ts]>const foo = "bar"</code>
HTTP based directives
mizu.js offers a set of directives inspired by htmx.
These directives are especially useful in server-rendering contexts for importing content, but they can also be used on the client side to perform HTTP requests.
<!-- Fetch and display remote content -->
<div %http="https://example.com" %response.html></div>
<div %http="https://example.com" %response.html="$content.querySelector('h1')"></div>
<!-- Make an HTTP POST request on click and show the response -->
<button
%http.post="https://example/api"
%header[x-foo]="'my custom header'"
%body.json="{ foo: 'bar' }"
%@click="alert(await $response.text())"
></button>
Working with HTML custom elements
While HTML natively supports custom elements, they can be a bit tedious to use.
mizu.js simplifies this process with a more concise syntax for defining and using custom elements in your documents.
<!-- Create a custom element -->
<template *custom-element="my-element">
<div *mustache>
There is {{ items.length }} items:
<ul><slot name="items"></slot></ul>
</div>
</template>
<!-- Use the custom element -->
<my-element>
<li #items>foo</li>
<li #items>bar</li>
</my-element>
Bonus: You can easily reuse your custom elements in other projects by importing them with a HTTP based directive!
<template
*custom-element="my-element"
%http="https://example.com/partial/my-element.html"
%response.html
></template>
Miscelleanous
I won't cover every available directive here, but there are many more to explore!
Here's a small selection of some interesting ones:
<!-- Automatically update the time every second -->
<!-- Perfect for elements where reactivity can't be tracked -->
<time *refresh="1" *mustache>{{ new Date() }}</time>
<!-- Execute raw code for special cases -->
<div *eval="this.remove()"></div>
Using mizu.js programmatically
So far, I've shown how to use mizu.js directly in your HTML documents, but you can also use it programmatically for more advanced use cases.
Because mizu.js directives are just plain HTML attributes, the syntax remains the same for both client-side and server-side rendering. This means you can easily switch between rendering environments without ever changing your templates!
import Mizu from "@mizu/render/server"
export default {
async fetch() {
const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" })
const body = await Mizu.render(`<div *text="foo"></div>`, { context: { foo: "π Yaa, mizu!" } })
return new Response(body, { headers })
},
}
Generating static sites
You can generate static sites easily
import Mizu from "@mizu/render/server"
await Mizu.generate([
// Copy content from /source/static to /dist/static
["**/*", "static", { directory: "/source/static" }],
// Copy and render content from /source/templates to /dist
["**/*", ".", { directory: "/source/templates", render: {} }],
// Copy content from a URL to /dist/styles.css
[new URL("https://matcha.mizu.sh/matcha.css"), "styles.css"],
// Copy content from callback return
[() => JSON.stringify(Date.now()), "timestamp.json"],
], { clean: true, output: "/dist" })
Start using mizu.js today!
Want to experiment with mizu.js without installing anything?
Checkout mizu.sh/playground!
lowlighter
/
mizu
π mizu.js is a lightweight html templating engine for any side rendering. No build steps, no config, no headaches.
Visit mizu.sh for a comprehensive overview!
Bonus: mizu.js pairs perfectly with matcha.css to make your websites look fantastic!
Top comments (0)