mizu.js

Supercharge your HTML!
File
Edit
View
Run
Terminal
Help
ssr.ts
ssg.ts
ssr.mjs
ssg.mjs
ssr.ts
ssg.ts
#!/usr/bin/env -S deno serve --allow-read --allow-env
// Server-Side Rendering (SSR) with Mizu
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 })
  },
}
#!/usr/bin/env -S deno run --allow-read --allow-env --allow-net --allow-write=/tmp/output
// Static Site Generation (SSG) with Mizu
import Mizu from "@mizu/render/server"

await Mizu.generate([
  // Copy content from strings
  [`<div *text="foo"></div>`, "index.html", { render: { context: { foo: "🌊 Yaa, mizu!" } } }],
  // Copy content from callback return
  [() => JSON.stringify(Date.now()), "timestamp.json"],
  // Copy content from local files
  ["**/*", "static", { directory: "/fake/path" }],
  // Copy content from URL
  [new URL("https://matcha.mizu.sh/matcha.css"), "styles.css"],
], { clean: true, output: "/tmp/output" })
1
2
3
4
5
6
7
8
9
10
11
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Server-Side Rendering (SSR) with Mizu
import Mizu from "@mizu/render/server"
import { createServer } from "node:http"

createServer(async (_, response) => {
  response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
  response.end(await Mizu.render(`<div *text="foo"></div>`, { context: { foo: "🌊 Yaa, mizu!" } }))
}).listen(8000, "0.0.0.0", () => console.log("Server is listening"))
// Static Site Generation (SSG) with Mizu
import Mizu from "@mizu/render/server"

await Mizu.generate([
  // Copy content from strings
  [`<div *text="foo"></div>`, "index.html", { render: { context: { foo: "🌊 Yaa, mizu!" } } }],
  // Copy content from callback return
  [() => JSON.stringify(Date.now()), "timestamp.json"],
  // Copy content from local files
  ["**/*", "static", { directory: "/fake/path" }],
  // Copy content from URL
  [new URL("https://matcha.mizu.sh/matcha.css"), "styles.css"],
], { clean: true, output: "/tmp/output" })
1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8
9
10
11
12
13
// Server-Side Rendering (SSR) with Mizu
import Mizu from "@mizu/render/server"

Bun.serve({
  port: 8000,
  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 })
  },
})

console.log("Server is listening")
// Static Site Generation (SSG) with Mizu
import Mizu from "@mizu/render/server"

await Mizu.generate([
  // Copy content from strings
  [`<div *text="foo"></div>`, "index.html", { render: { context: { foo: "🌊 Yaa, mizu!" } } }],
  // Copy content from callback return
  [() => JSON.stringify(Date.now()), "timestamp.json"],
  // Copy content from local files
  ["**/*", "static", { directory: "/fake/path" }],
  // Copy content from URL
  [new URL("https://matcha.mizu.sh/matcha.css"), "styles.css"],
], { clean: true, output: "/tmp/output" })
1
2
3
4
5
6
7
8
9
10
11
12
13
1
2
3
4
5
6
7
8
9
10
11
12
13
Terminal
Output
Ports
dev@mizu:~ $
deno add jsr:@mizu/render
npx jsr add @mizu/render
bunx jsr add @mizu/render
IIFE
ESM
🌊 Yaa, mizu!
Elements 
<!DOCTYPE html>
<html>
  <head>
    <title>IIFE</title>
    <meta charset="UTF-8" />
  </head>
  <body>
    <main *mizu *set="{ foo: '🌊 Yaa, mizu!' }">
      <div *mustache>{{ foo }}</div>
    </main>
    <!-- Use the IIFE version to automatically start mizu -->
    <script src="https://mizu.sh/client.js" defer></script>
  </body>
</html>
<!DOCTYPE html>
<html>
  <head>
    <title>ESM</title>
    <meta charset="UTF-8" />
  </head>
  <body>
    <main *mizu>
      <div *mustache>{{ foo }}</div>
    </main>
    <!-- Use the ESM version to manually control mizu -->
    <script type="module">
    import Mizu from "https://mizu.sh/client.mjs"
    await Mizu.render(document.body, { context: { foo: "🌊 Yaa, mizu!" } })
    </script>
  </body>
</html>
browsers
deno
node
bun

Switch between browsers and runtimes using the icons above.
Change the current example by clicking on the tabs in the mockups.

Try out our online interactive playground and start experimenting with mizu.js now!

Features

Plug-and-play

Simply include the library and start building amazing things instantly with vanilla JavaScript expressions and HTML.

Cross-platform

Compatible across a wide range of JavaScript and TypeScript runtimes, including all major browsers.

Any-side

Render your content wherever you need it and however you want it with user-friendly APIs.

Hackable

Cherry-pick features and craft your own setup easily with developer-friendly APIs and our custom builder.

Community-driven

Build, share and reuse custom elements and directives to supercharge your development.

Want to effortlessly theme your page? Check out matcha.css!

Free & Open-source

Licensed under the MIT License and source code fully available on github.com.

If you enjoy using mizu.js, consider supporting its development.

FAQ

Another web library? Really?

Yes, but hear us out!

Remember when building a web page was as simple as writing some HTML, adding a bit of JavaScript, and styling with CSS? mizu.js brings back that simplicity, offering a modern yet flexible approach to web development.

By adhering closely to web standards and embracing the simplicity of plain HTML and JavaScript, mizu.js offers an almost non-existent learning curve. This makes it an excellent choice for both beginners and seasoned developers.

Whether you're serving content from your favorite runtime, generating static websites, or creating dynamic pages in the browser, mizu.js adapts to your needs. — All of it without the hassle of bundlers, transpilers, or countless dependencies.

Why should I use mizu.js over other web frameworks?

We recognize the power and utility of comprehensive frameworks like React, Vue.js, and Angular. These tools excel at building complex applications and boast large communities and ecosystems. However, they can be overwhelming for smaller projects, often requiring a build step and a steep learning curve with their specific syntax and concepts.

Lightweight alternatives such as Alpine.js and htmx are also available. While they perform well in the browser, they were often not designed for server-side use, limiting their applicability across different scenarios.

mizu.js draws inspiration from all these frameworks but is designed from the ground up to be:

  • Flexible, suitable for single page applications, static websites, interactive websites, and more.
  • Versatile, works both client-side and server-side and in the runtime of your choice.
  • Simple, close to vanilla JavaScript and HTML and a minimal learning curve.
  • Customizable, easily opt-in/opt-out of features.

If all of this sounds appealing to you, then mizu.js might be the right choice for your next project.

Does mizu.js use a Virtual DOM?

It depends.

On the server-side, mizu.js employs a Virtual DOM to simulate the browser environment. The current implementation leverages JSDOM, but you can use any other Virtual DOM library that adheres to web standards. Non-compliant implementations may lead to unexpected behaviors.

On the client-side, mizu.js interacts directly with the actual DOM. It tracks processed elements and their states using weak references to prevent memory leaks and enhance performance.

How reliable is mizu.js?

We want to ensure mizu.js delivers a reliable and consistent experience across all supported environments, which is why each feature is meticulously documented to detail its behavior and functionality.

Our codebase is thoroughly tested and covered to guarantee that each feature performs as expected. Integration tests are also performed on various platforms and environment to ensure a consistent experience as advertised.

If you encounter any issues or undocumented behavior, please open a new issue so we can address it promptly.

What does the name mizu mean?

æ°´(mizu) is the Japanese kanji for water.

Like water, mizu.js is fluid and adaptable, seamlessly fitting into various use cases and execution environments.

Like water, mizu.js is simple and fundamental, staying close to vanilla JavaScript and HTML with a minimal learning curve.

Like water, mizu.js is customizable, it can be mixed with other libraries and additional features to suit your needs.

Need to add some flavor to your page? Add some matcha.css to your mizu.js project!
Looking for something? Jump to section:

Directives

Rendering

*mizu

Enable mizu.js rendering for the element and its children.

For performance reasons, this directive must not have any [tag] or .modifiers. If it does, the directive will be ignored. You can choose whether to require this directive for mizu.js rendering with the implicit option when using the user API. By default, rendering is explicit in Client-Side APIs and implicit in Server-Side APIs. HTMLElement The closest element that declares a *mizu directive.

Contextual

*set="context"

Set context values for an element and its children.

The context must resolve to a JavaScript Object. The context is initialized once and persists across renderings, but it can still be updated by other directives.
*ref="name"

Create a reference to an element for later use.

Record<PropertyKey, HTMLElement> A collection of all referenced elements within the current subtree. Redefining a reference will shadow its previous value within the current subtree, without affecting its value in the parent subtree. Skip expression evaluation if set.

Conditional

*if="expression"

Conditionally render an element.

When used on a <template> element, its content is rendered in place of the template which allows to conditionally render several elements at once.
*else="expression"

Conditionally render an element placed after another *if or *else directive.

Must be placed immediately after an element with an *if or *else directive. When used on a <template> element, its content is rendered in place of the template which allows to conditionally render several elements at once.
*show="expression"

Conditionally display an element.

When hidden, the element's CSS display property is set to none !important. When shown and if initially hidden by a CSS stylesheet (display: none), the element's display property is reset to initial !important. Unlike *if and *else directives, the element remains in the DOM when hidden. You can take advantage of the default value being true to hide elements before mizu.js loads (e.g. <style>[\*show]{display:none}</style>).

Iterative

*for="expression"

Render an element for each iteration performed.

  • The expression can be:
    • Any syntax supported inside for, for...in and for...of loops.
    • Any iterable object that implements Symbol.iterator.
      • The iterated key is exposed as $key.
      • The iterated value is exposed as $value.
    • A finite number.
      • The directive is applied the specified number of times.
     There is currently no distinction between let, const and var declarations inside for loops, but future versions may introduce specific behavior for these. When used on a <template> element, its content is rendered for each iteration instead of the element itself which allows to generate several elements per iteration. string The evaluated value of the *id directive if present, or the auto-generated identifier. number The total number of iterations. number The current iteration index (0-based). number The current iteration index (1-based, same as $i + 1). number Whether this is the first iteration (same as $i === 0). number Whether this is the last iteration (same as $i === ($iterations - 1)).     *id="expression"

    Hint for *for directive to differentiate generated elements.

  • Must be used on an element with a *for directive. Identifiers must be unique within the loop, any duplicates will be replaced by the last occurrence. When used on a <template> element, identifiers are only tracked internally and no attribute is set on the generated content.
    *empty

    Conditionally render an element after a *for directive.

    Must be placed immediately after an element with a *for or another *empty directive. Elements generated by the *for directive do not apply to this restriction. There is currently no special handling for <template> elements, but future versions may introduce specific behavior for these elements. number The number of elements generated by the preceding *for directive. This value may differ from the actual number of iterations processed if conditional directives were applied. Inverts the condition, rendering the element when at least one element is generated.

    Content

    *text="content"

    Set element's textContent.

    HTML content is automatically escaped. Without an attribute value, this directive escapes the element's innerHTML (e.g., <a *text><b></b></a> becomes <a *text>&lt;b&gt;&lt;/b&gt;</a>).
    *html="content"

    Set element's innerHTML.

    Raw HTML can introduce XSS vulnerabilities. Exercise caution when using expressions from untrusted sources.
    *mustache

    Enable content interpolation within mustaches ({{ and }}) from Text child nodes.

    Interpolation occurs only within Text nodes, not the entire element. HTML content is automatically escaped. There is currently no distinction between double mustaches ({{ and }}) and triple mustaches ({{{ and }}}), but future versions may introduce specific behavior for these.
    *code="content"

    Set element's innerHTML after performing syntax highlighting.

    This directive dynamically imports highlight.js. Unsupported languages default to plaintext. string Any supported language identifier or alias. Remove leading/trailing whitespaces and shared indentation.
    *markdown="content"

    Set element's innerHTML after performing markdown rendering.

    This directive dynamically imports @libs/markdown. Load additional Markdown plugins by specifying a comma-separated list (e.g., *markdown[emojis,highlighting,sanitize]). See the full list of supported plugins at @libs/markdown/plugins. Unsupported plugins will be silently ignored. Trim the leading spaces before rendering content. Unwrap rendered content when it results in a single <p> tag.
    *toc="selector"

    Create a table of contents from <h1>...<h6> elements found in selected target.

    Heading elements must meet these criteria:
    • Include an id attribute.
    • Contain an immediate <a> child with an anchor link pointing to its parent id.
    • Follow a descending order without skipping levels.
     When a heading is found, the next level headings are searched within its parentElement. If the parent is an <hgroup> or has a *toc[ignore] attribute, the search moves to the grandparent element. string Define which heading levels to include:
    • Specify a single level (e.g., *toc[h2]).
      • Add a + to include higher levels (e.g., *toc[h2+]).
    • Use a range with a - to specify multiple levels (e.g., *toc[h2-h4]).
    • Use ignore to exclude an element from traversal (e.g., *toc[ignore]). No other modifiers or attribute value should be used with this.
    *clean

    Clean up the element and its children from specified content.

    Remove all Comment nodes within the subtree. Remove all spaces (except non-breaking spaces &nbsp;) within the subtree. Clear all <template> nodes from the subtree after fully processing it. Strip all known directives from the subtree after fully processing it. If the .comments modifier is also enabled, comments generated by directives will be removed as well.

    Custom elements

    *custom-element="tagname"

    Register a new custom element.

    Must be defined on a <template> element. The tagname must be a valid custom element name. Valid custom element names may be specified as is. Custom elements registered this way do not use Shadow DOM, their content is rendered directly. Record<PropertyKey, HTMLSlotElement> A record of #slot elements by <slot> name. The unnamed slot is accessible using $slots[""]. Record<PropertyKey, string> A record of HTML attributes specified on the custom element. Apply *once.flat directive on the custom element occurences.     #slot

    Specify target <slot> in an element defined by a *custom-element directive.

    • Elements without a #slot directive are appended to the default (unnamed) slot. Elements targeting the same slot are appended in the order they are defined.
    *is="tagname"

    Set an element tagname.

    If the tagname changes, the reference will also change. Equality checks with elements using this directive may not work as expected. Some directives may be incompatible with this directive.

    Events

    @event="listener"

    Listen for a dispatched Event.

    Attach multiple listeners in a single directive using the shorthand @="object" (e.g., @="{ foo() {}, bar() {} }").
    • Modifiers apply to all listeners in the directive (e.g., @.prevent="{}").
    • Use tags to attach listeners with different modifiers (e.g., @[1]="{}" @[1].prevent="{}").
    • HTML attributes are case-insensitive, so this is the only way to listen for events with uppercase letters or illegal attribute characters (e.g., @="{ FooBar() {}, Foobar() {} }").
     To listen for events with dots . in their names, use brackets {} (e.g. @{my.event}). Event (in listener only) The dispatched Event. Optional tag to attach multiple listeners to the same event (e.g., @click[1], @click[2], etc.). Call event.preventDefault() when triggered. Call event.stopPropagation() when triggered. Register listener with { once: true }. Register listener with { passive: true }. Register listener with { capture: true }. Trigger listener only if event.target is the element itself. Attach listener to a different target (e.g., window or document). Prevent listener from being called more than once during the specified time frame. Delay listener execution until the specified time frame has passed without any activity. Specify which keys must be pressed for the listener to trigger on a KeyboardEvent.
    • The syntax for keys constraints is defined as follows:
      • Combine keys with a plus sign + (e.g., @keypress.keys[ctrl+space]).
      • Separate multiple combinations with a comma , (e.g., @keypress.keys[ctrl+space,shift+space]).
    • Supported keys and aliases:
      • alt for "Alt".
      • ctrl for "Control".
      • shift for "Shift".
      • meta for "Meta".
      • space for " ".
      • key for any key except "Alt", "Control", "Shift", and "Meta".
      • Any value returned by event.key.

    Binding

    :attribute="value"

    Bind an element's attribute value.

    Binding directives is not officially supported and is considered undefined behaviour. :class and :style have specific handling described below. Bind multiple attributes in a single directive using the shorthand :="object" (e.g. :="{ foo: 'bar', bar: true }"). The directive value may be omitted to bind an attribute to an identifier with the same name (after camelCase conversion if the attribute contains hyphens -) in the current context. (e.g., :data-foo is equivalent to :data-foo="dataFoo"). Boolean attributes defined by the HTML spec are handled accordingly (removed when falsy). Attributes with null or undefined values are removed.     :class="value"

    Bind an element's class attribute.

    The expression can be:
    • A string of space-separated class names (e.g., "foo bar").
    • A Record<PropertyKey, boolean> mapping class names to their state (e.g., { foo: true, bar: false }).
    • An Array of the supported types (e.g., [ "foo", { bar: false }, [] ]).
    The initial class attribute value is preserved. Class names with at least one truthy value are treated as active.     :style="value"

    Bind an element's style attribute.

    The expression can be:
    • A string supported by HTMLElement.style.cssText (e.g., "color: blue;").
    • A Record<PropertyKey, unknown> mapping CSS properties to their values (e.g., { backgroundColor: "red", "border-color": "green", width: 1 }).
    • An Array of the supported types (e.g., [ "color: blue", { backgroundColor: "red" }, [] ]).
    The initial style attribute value is preserved. CSS properties are processed in the order they are defined, regardless of !important.

    Modeling

    ::value="model"

    Bind an <input>, <select> or <textarea> element's value attribute in a bi-directional manner.

    <input type="checkbox"> and <select multiple> elements will bind to an array of values. Using a modeled value within @input or @change expressions can cause precedence issues, as the model relies on these events to update. To avoid this, listen to the :: event, which is always triggered after the model has been updated. Must be used on elements with a value property, such as <input>, <select>, or <textarea>. For other elements, use the :attribute directive. The .nullish, .boolean, .number, and .string modifiers are currently implemented as boolean modifiers, but future versions may change this behavior to offer more parsing features. You can use the shorthand syntax ::="model" instead of ::value="model". Change the Event that triggers the model update. Recommended events are "input" or "change". Automatically set the input name attribute based on the attribute's value (e.g., <input ::.name="foo"> becomes <input name="foo">). The default is true for <input type="radio"> and <input type="checkbox">, and false for all other elements. Initialize the model using the nullish coalescing operator and the input value attribute if present (e.g., <input ::.value="foo" value="bar"> assigns foo the value "bar" if it was nullish). Prevent the listener from being called more than once during the specified time frame. Delay listener execution until the specified time frame has passed without any activity. Specify which keys must be pressed for the listener to trigger on a KeyboardEvent. See @event.keys modifier for more information. Set the model value to null if the value is empty. Convert the model value using Boolean(). Additionally, any non-empty value matching the YAML 1.1 definition of falsy boolean values are set to false. Convert the model value using Number(). Convert the model value using String().

    HTTP

    %http="url"

    Perform a fetch() call that can be handled by %response directives.

    Without a %response directive, the request won't be performed automatically. Use %response.void if you want to trigger the request but ignore the response. Valid URLs may be specified as is. A new request is triggered for the same element if:
    • Its reference changes.
    • The evaluated URL changes.
    Since predicting when a new request will be performed is challenging, use this directive only for read-only operations. For endpoints with side effects, consider the %@event directive.     Event | null (in url expression only) The dispatched Event if triggered by a %@event directive, or null. Control whether fetch() should follow redirections. Whether to update the browser history with history.pushState() for the target URL (must be the same origin). Set the HTTP method (the value is uppercased). This modifier should not be used with its aliases. Alias for .method[get]. Alias for .method[head] Alias for .method[post] Alias for .method[put] Alias for .method[patch] Alias for .method[delete]     %header[name]="value"

    Set HTTP headers for a %http directive.

    Headers with undefined or null values are deleted. Headers with Array values are appended together. Header name.     %body="content"

    Set HTTP body for a %http directive.

    Headers A Headers object containing all registered headers from %header directives attached to the element. Format the body with the specified type: This modifier should not be used with one of its aliases. Automatically set the Content-Type header when using a .type modifier:
    • text: set Content-Type: text/plain.
    • form: set Content-Type: application/json.
    • json: set Content-Type: application/x-www-form-urlencoded.
    • xml: set Content-Type: application/xml.
    If the header was already set, it is overwritten.     Alias for .type[text]. Alias for .type[form]. Alias for .type[json]. Alias for .type[xml].     %response="expression"

    Reacts to a %http directive's Response.

    Response A Response object containing the fetched data. unknown Contains the response.body (type depends on the modifier used). string Specify which HTTP status codes trigger this directive:
    • The syntax for status code constraints is defined as follows:
      • Define a range using a minus sign - between two numbers (e.g., %response[200-299]).
      • Specify multiple ranges and statuses by separating them with a comma , (e.g., %response[200,201-204]).
    • Supported aliases:
      • 2XX for 200-299.
      • 3XX for 300-399.
      • 4XX for 400-499.
      • 5XX for 500-599.
    Consume the response.body: This modifier should not be used with one of its aliases. Alias for .consume[void]. Alias for .consume[text]. Alias for .consume[html]. Alias for .consume[json]. Alias for .consume[xml].

    Consume body using response.text() and set target's outerHTML. This modifier takes precedence over the .consume modifier and makes it effectless, although if .consume[text] is set, swapped content will be escaped.

    Any non-directive HTML attributes on the target will be applied to the swapped content elements.

    This modifier automatically triggers a re-render of the replaced element's parent.

    %@event="listener"

    Listen for a dispatched Event and re-evaluates %http directive before reacting to its Response.

    Must be defined on an element that also possess a %http directive. This is essentially a combination of %response and @event directives. Target URL is still set by %http directive. As it is re-evaluated, you can however use the $event value to dynamically compute the target URL (e.g.%http="$event ? '/foo' : '/bar'"). All modifiers from %http directive are inherited, along with the RequestInit prepared by %header and %body directives. Event (in listener only) The dispatched Event. Response A Response object that contains the fetched data. unknown A variable that contains the response.body (typing depends on which modifier is used). Inherited from @event and %response directives. See their respective documentation for more information.

    Processing

    *once

    Render an element once and skip subsequent updates.

    Replace this element by its content.
    *refresh="interval"

    Reprocess an element at a specified interval (in seconds).

    Ensure proper context management to prevent unexpected errors. Avoid using with iterative directives like *for as *refresh will be duplicated for each generated element. The target element will be rendered regardless of detected changes. This is useful for updating content that cannot be directly observed, but use sparingly to avoid performance issues. Set the interval to null to stop refreshing. If the element is commented out by a directive, the refresh is automatically cleared. Refresh operations are performed using setTimeout. New calls are scheduled when the directive is processed again, ensuring a consistent interval. boolean Indicates if the element is currently being refreshed.
    *eval="expression"

    Evaluate a JavaScript expression in the context of the element.

    Use this directive sparingly, prefer alternative directives for better maintainability and security. This directive is intended for edge cases. The expression runs after the element and all its children have been fully processed.
    *skip

    Prevent an element from being processed.

    Testing

    These directives are for development and testing purposes only. They help developers validate features and renderings before production.

    Do not use in production environments.

    ~test="expression"

    Special directive for testing purposes.

    For testing only. Use this directive to isolate and test custom directives without relying on others. The modifiers may not be compatible with each other. string Specify any existing Phase name (e.g., ~test[testing], defaults to Phase.TESTING). The directive will execute during the specified phase before any other directive in that phase, allowing you to simulate specific scenarios. Set the element's textContent with the expression result. Evaluate a JavaScript expression within the element's context. Convert the element to a Comment if the expression is truthy, and revert it otherwise. Throw an EvalError if the expression is truthy.

    Unstable

    New features that are still in the design phase are published in this package to gather community feedback. These features may undergo significant changes during development and might not be included in the stable release.

    Use at your own risk.

    *noop

    This directive does nothing.

    Usage

    Client-side

    Set up mizu.js in your browser environment using one of two methods:

    On the client-side...

    • Rendering is explicit, requiring the *mizu attribute to enable mizu.js on a subtree.
    • Reactivity is enabled, so changes to contexts will trigger a re-render.

    IIFE (.js)

    This setup automatically starts rendering the page once the script is loaded. It's the simplest way to get started but limited to the default configuration. 

    <script src="https://mizu.sh/client.js" defer></script>

    ESM (.mjs)

    This setup requires you to import and start mizu.js manually, allowing customization of the rendering process, such as setting the initial context and loading additional directives. 

    <script type="module">
      import Mizu from "https://mizu.sh/client.mjs"
      await Mizu.render(document.body, { context: { foo: "🌊 Yaa, mizu!" } })
    </script>

    Looking to effortlessly theme your new web page? Check out matcha.css! 

    <link rel="stylesheet" href="https://matcha.mizu.sh/matcha.css">

    Server-side

    To set up mizu.js in a server environment, install it locally. mizu.js packages are hosted on jsr.io/@mizu.

    On the server side...

    • Rendering is implicit, so the *mizu attribute is not required.
    • Reactivity is disabled, meaning changes to contexts are not tracked and will not trigger a re-render.

    Deno

    Deno supports the jsr: specifier natively, allowing you to import mizu.js directly. 

    import Mizu from "jsr:@mizu/render/server"
await Mizu.render(`<div *text="foo"></div>`, { context: { foo: "🌊 Yaa, mizu!" } })

    Alternatively, add it to your project using the Deno CLI. 

    deno add jsr:@mizu/render

    Other runtimes (NodeJS, Bun, etc.)

    Add mizu.js to your project using the JSR npm compatibility layer. 

    # NodeJS
npx jsr add @mizu/render
    # Bun
bunx jsr add @mizu/render

    Once installed, use it in your project. 

    import Mizu from "@mizu/render/server"
await Mizu.render(`<div *text="foo"></div>`, { context: { foo: "🌊 Yaa, mizu!" } })

    Concepts

    Directive

    A HTML attribute recognized by mizu.js which instructs how it should process the element.

    The syntax is as follows:

    <tag 
    *name
    [tag]
    .modifier
    [value]
    ="expression"
     />

    Name

    Directives names often begin with special characters to prevent conflicts with standard HTML attributes and to clearly indicate their specific purpose:

    • * for generic directives.
    • # for directives targeting <slot> elements.
    • @ for directives related to Event handling.
    • : for binding HTML attributes.
      • :: for bi-directional binding.
    • % for HTTP directives.
      • %@ for combined HTTP and Event directives.
    • ~ for testing directives.

    Tag

    Typically, this serves as the directive's argument. At most one tag can be specified per directive.

    Modifier(s)

    Modifiers adjust the behavior of the directive. You can specify multiple modifiers on the same directive.

    Repeating a modifier on a single directive is considered undefined behavior.

    Modifier(s) value

    The value of the modifier. The modifier may have an explicit default value, which is used if no value is specified.

    The value is validated and cast to the expected type, defaulting if invalid. Modifiers may accept one of the following types:

    • boolean , unset defaults to true.
    • string , unset defaults to "".
    • number , unset defaults to 0.
    • duration , unset defaults to 0ms (supported units: ms, s, m).

    JavaScript Expression

    Set through the HTML attribute value, it is evaluated asynchronously within the context of the current element during processing.

    A directive may have a Default expression, used when no specific expression is provided.

    Unless stated otherwise, any JavaScript expression is permitted.

    The full capabilities of the JavaScript engine is available, including its potential risks. Exercise caution when using expressions from untrusted sources.

    Context

    All expressions are evaluated within a specific context, which includes all defined variables and functions. You can define these through the user API or directly via contextual directives.

    Certain directives may also provide special variables based on the current processing state, prefixed with a dollar sign ($).

    Although you can also prefix your variables with a dollar sign ($), it is recommended to avoid this practice to prevent confusion with special variables. In case of a conflict, the special variables will shadow user-defined ones until being shadowed themselves. The identifier __mizu_internal is reserved and cannot be used in expressions.

    Reactivity

    mizu.js leverages @libs/reactive to monitor context changes and trigger re-renders as needed.

    During element processing, all get operations are cached with the element as a reference. Whenever a set operation is performed, mizu.js identifies which elements depend on the changed value and re-processes them.

    Reactivity is enabled by default on the Client-side but disabled by default on the Server-side. Although @libs/reactive can track function calls, mizu.js currently does not support reprocessing elements that depend on them. This is because expressions are re-evaluated with each re-render, which would re-trigger the function call. Future versions of mizu.js may introduce a mechanism to prevent this behavior.

    Rendering

    Rendering is the process of evaluating and applying mizu.js directives. This occurs recursively on a subtree and modifies the current DOM.

    Rendering process schema explanation
    Element rendering

    Node is an Element OR Node is in cache

    Resolve source node IF in cache

    Directives setup

    Returned value is false

    Call directive.setup()

    Update state IF present in returned value

    Set forced eligibility IF present in returned value

    Directives execution

    Node has a matching attribute OR eligibility has been forced to true during setup

    Node has NO matching attributes OR eligibility has been forced to false during setup

    Returned value has final set to true

    Call directive.execute()

    Notify any misuses IF applicable (e.g. conflicts, duplicates, etc.)

    Replace current node reference IF present in returned value

    Update state IF present in returned value

    Update context IF present in returned value

    Recursively call rendering on node children

    Directives cleanup

    Call directive.cleanup()
    Dynamically adding and removing mizu.js directives is not officially supported. While it may work currently due to the rendering engine's lack of optimization, future versions may cache directives to enhance performance. This change would prevent dynamically added directives from being processed.

    Phase

    Each directive is tied to a specific phase, dictating the order of processing. The sequence in which directives appear on an element is irrelevant unless they share the same phase.

    Directives within the same phase cannot coexist on the same element unless explicitly allowed to be specified Multiple times.

    Using conflicting directives on the same element results is considered undefined behavior.
    Phase list
    • 00 META
    • 01 ELIGIBILITY
    • 02 PREPROCESSING
    • 10 TESTING
    • 11 CONTEXT
    • 21 EXPAND
    • 22 MORPHING
    • 23 TOGGLE
    • 31 HTTP_HEADER
    • 32 HTTP_BODY
    • 33 HTTP_REQUEST
    • 34 HTTP_CONTENT
    • 35 HTTP_INTERACTIVITY
    • 41 CONTENT
    • 42 CONTENT_INTERPOLATION
    • 49 CONTENT_CLEANING
    • 51 ATTRIBUTE
    • 52 ATTRIBUTE_MODEL_VALUE
    • 59 ATTRIBUTE_CLEANING
    • 61 INTERACTIVITY
    • 71 DISPLAY
    • 81 CUSTOM_ELEMENT
    • 82 REFERENCE
    • 89 CUSTOM_PROCESSING
    • 99 POSTPROCESSING

    API

    User API

    This section is targeted at users who want to use mizu.js rendering and directives.

    If you wish to develop custom directives, please refer to the Developer API section instead.

    Client-side API

    Full API documentation is available at jsr.io/@mizu/render/client.

    Defaults directives

    The following directives are enabled by default in the client-side API. You can customize the enabled directives by creating a custom instance rather than using the default one.

      Client.context: Record<PropertyKey, any>

      Rendering context.

      All properties assigned to this object are available during rendering.

      Changes to this object are reactive and will trigger a re-render of related elements. This is achieved using Context, which leverages Proxy handlers.

      You cannot reassign this property directly to ensure reactivity is maintained. To achieve a similar effect, use Object.assign().

      Server-side API

      Full API documentation is available at jsr.io/@mizu/render/server.

      Defaults directives

      The following directives are enabled by default in the server-side API. You can customize the enabled directives by creating a custom instance rather than using the default one.

        Server.generate(sources: Array<StringSource | GlobSource | CallbackSource | URLSource>, options?: ServerGenerateOptions) => Promise<void>

        Generate static files from various sources.

        Options:

        • output: Specify the path to the output directory.
        • clean: Empty the output directory before generating files.

        Supported sources:

        • StringSource: Generate content from raw strings.
        • GlobSource: Generate content from local files matching the provided glob patterns.
        • CallbackSource: Generate content from callback returns.
        • URLSource: Generate content from fetched URLs.

        Each source can be templated using mizu rendering by passing a render option.

        const mizu = new Server({ directives: ["@mizu/test"], generate: { output: "/fake/output" } })
await mizu.generate(
  [
    // Copy content from strings
    [ "<p>foo</p>", "string.html" ],
    [ "<p ~test.text='foo'></p>", "string_render.html", { render: { context: { foo: "bar" } } } ],
    // Copy content from local files
    [ "**\/*", "public", { directory: "/fake/static" } ],
    [ "*.html", "public", { directory: "/fake/partials", render: { context: { foo: "bar "} } } ],
    // Copy content from callback return
    [ () => JSON.stringify({ foo: "bar" }), "callback.json" ],
    [ () => `<p ~test.text="'foo'"></p>`, "callback.html", { render: { context: { foo: "bar" } } } ],
    // Copy content from URL
    [ new URL(`data:text/html,<p>foobar</p>`), "url.html" ],
    [ new URL(`data:text/html,<p ~test.text="foo"></p>`), "url_render.html", { render: { context: { foo: "bar" } } } ],
  ],
  // No-op: do not actually write files and directories
  { fs: { readdir: () => Promise.resolve([] as string[]), mkdir: () => null as any, write: () => null as any } },
)

        Developer API

        This section is targeted at developers who want to create custom mizu.js rendering and directives.

        If you wish to render templates, please refer to the User API section instead.

        Directive API

        Full API documentation is available at jsr.io/@mizu/internal/engine.

        This section covers the Directive interface, essential for creating custom directives. Each built-in directive is also an instance of this interface. It follows the steps outlined in the Rendering concept.

        When manipulating the DOM, use the Renderer methods to ensure compatibility between virtual and real DOMs. These methods also provide helpful tools to simplify the creation of custom directives.

        Internal API

        Full API documentation is available at jsr.io/@mizu/internal.

        This package includes several APIs used by mizu.js, such as the Renderer, virtual DOM implementations, the testing framework, and more. These symbols are documented in the source code and are intended for development environments.

        To Be Defined

        mizu.js currently follows ZeroVer versioning. This means breaking changes may occur in minor versions, even for previously defined features.

        It will eventually stabilize and follow SemVer versioning after more feedback and testing.

        Some aspects of mizu.js are not fully defined yet. While these are mentioned in the documentation, they are gathered here for easy reference.

        Relying on undefined behavior in your applications is strongly discouraged, as these behaviors may change in future versions without being considered breaking changes. Additionally, any unusual behavior encountered is not considered a bug until properly specified.

        If you wish to participate in the design and definition of these features, check out the issues tagged with spec.