Show HN: Mizu.js – Lightweight HTML templating library for any-side rendering

[lowlighter]

Hey HN,

I'd like to share a fun project I've been working on: mizu.js.

It's a js library that add functional attributes support into your html, designed to be a simple and flexible alternative to fully-fledged web frameworks (such as Vue, React, and Angular), while offering more capabilities than other lightweight options (like Alpine.js and htmx).

As it's written using modern ES features and due to its isomorphic nature, it can be run in both browsers and runtimes (Node, Deno, Bun) without any changes. This makes it ideal for client-side and server-side rendering, as well as static site generation, whichever environment you prefer.

Just include the script in any web page (or backend) to get started. You can template content, bind attributes, add interactivity, handle HTTP interactions, create custom components, and much more — all out of the box, without any configuration, transpilation steps, or builds.

I hope you'll find mizu.js as exciting and useful as I do and I'd love to get your feedback! You can learn more about it at https://mizu.sh!

Online playground: https://mizu.sh/playground Custom builder: https://mizu.sh/build Code coverage: https://mizu.sh/coverage GitHub: https://github.com/lowlighter/mizu

## Motivation ##

Nowadays, setting up a complete environment and installing thousands of packages is often required just to create a simple "Hello World" page. Yet, with the current ECMAScript standard, vanilla JS has never been more powerful. It offers built-in custom HTML components, proxies for changes tracking, weak references for better memory management, and many new data structures and methods.

So why is web development still insanely complex?

mizu.js aims to avoid adding bloat on top of native features, and instead focus on providing convenience helpers. It's basically "glue" around all these native features with added sugar, a recipe for a lightweight yet powerful utility.

All evaluated expressions are interpreted as vanilla JavaScript, and you add your instructions directly into your HTML. So if you know already know about JS/HTML, then you're already 80% know of how to use mizu.js (add an extra 10% if you've used Vue, Alpine.js or htmx in the past as some syntax and concepts are inspired by it), the rest is basically just remembering the directive names. The learning curve is that small.

Also, you may have heard of https://matcha.mizu.sh, a CSS stylesheet to instantly make your web page stylized. Well, it's a great companion to mizu.js. With both of them, you can create MVPs for your projects super fast!

[esco27]

I appreciate the no-build-step approach. It’s refreshing to see a return to simplicity, even if it feels cyclical—similar libraries have come and gone, but that’s how the web evolves. As browsers continue to improve and embrace web standards, it makes sense to lean into tools that trend toward minimalism and simplicity. Great job!

[spankalee]

I love that this lets you create custom elements! I think that's a big missing feature from HTMX (even though HTMX can already use custom elements).

I'm working on a somewhat similar system called Heximal. It focuses on adding full-fledged templating to the <template> element, and full declarative component definitions to HTML, plus some built-in custom elements like <h-var>, <h-out>, <h-scope>, <h-include>, and <h-fetch> that make HTML more of a declarative programming language.

A big difference from HTMX is that it doesn't rely on magic attributes, but instead adds full data-binding with rich expressions for any attribute or text content, and control flow, to <template>. And component definitions include defining properties, attributes, styles, etc.

These things are being proposed for HTML, so Heximal is somewhat of a polyfill for HTML from the future. Or it's a bit like Tangle or Curvenote.

https://github.com/elematic/heximal/

[mdhb]

I’m so glad you’re still working on this, I hadn’t seen any updates in the repo lately and wasn’t sure if you changed focus areas or something.

[pickpuck]

Does it implement the proposed Declarative Custom Element spec with slice templating?

https://github.com/EPA-WG/custom-element

[corinroyal]

I love the information architecture of this site. You jump right in to demonstration code and a reference and only later the marketing text. So refreshing. I can see at a glance what the project is and what makes it different. Kudos!

[lowlighter]

Thanks! It's always hard to find a nice balance between explaining your project and showing how it actually work

[replwoacause]

Here is an alternative without the funky license

https://data-star.dev

[brianzelip]

Interesting license:

This project is dual-licensed.

You may use this project under the terms of the MIT License for non-commercial projects OR as long as you are sponsoring this project through GitHub sponsors with a monthly minimum donation of 1 (one) dollar using the link below:

    GitHub sponsors, Simon Lecoq: <https://github.com/sponsors/lowlighter>

You may use this project free of charge under the terms of the GNU Affero v3.

Via https://github.com/lowlighter/mizu?tab=readme-ov-file#-licen...

[johncoltrane]

The documentation was a pretty interesting read until "AGPLv3".

[withinboredom]

heh. "use it on the server" ... oops, you triggered the networking clause of the AGPL, and now your entire backend is open source.

[replwoacause]

This is AWESOME We need more of this kind of innovation and less React and Node bloat. Love the simplicity here, thank you.

EDIT: never mind the license killed it for me. Cool innovation but unusable with its AGPLv3 license.

[omtinez]

Really cool work, congrats!

I built my own frontend framework for similar reasons: https://github.com/fresho-dev/mancha. It was meant to adress the lack of lightweight solutions that worked both on the frontend and the backend. The main goal was to start with client side rendering and, only if you reach the point where you need it, switch to server side rendering. It also includes a drop in replacement for TailwindCSS except it won't yell at you for doing everything client side.

What I really wanted was a better maintained version of PetiteVue. But that highlights another problem: I simply can't trust anyone in the frontend JavaScript ecosystem, I've been burned too many times. It took a while to get to the point of it being usable, but now I know no one can pull the rug from under me. I use only the most basic APIs possible, only 1-2 third party dependencies, and as little hacks as possible.

It still has a few warts here and there but I hope to be able to call it a 1.0 stable version soon enough.

[replwoacause]

Mancha looks awesome, will follow the repo! Hope to see it reach v1.

[Vampiero]

Get it? Because mizu means water in Japanese?

[serial_dev]

In Hungarian, mizujs means "what's up", and it's often shortened to mizu, so, having a mizu.js JavaScript library would be a pretty cool name (for us who understand Hungarian).

https://glosbe.com/hu/en/mizujs

[lowlighter]

Maybe it'd feel weird for a native speaker to have something named "Water", but it does sound cool.

But that's also related to another project of mine, matcha (which is a kind of tea) which is a semantic css stylesheet.

Both were designed as a mini-ecosystem, kind like how you would put tea in your water

[ender1235]

The Japanese name makes it cool and fancy :).

[replwoacause]

Reminds me of hibiki html (now dead)

https://www.hibikihtml.com

And kind of like Imba:

https://imba.io

[pvg]

A related thread about half a year ago https://news.ycombinator.com/item?id=40455944

[toastercat]

I actually really love this, and have been wanting something like this for a while. Excited to give it a try.

[replwoacause]

Same until I saw the AGPLv3 license or forced subscription.

[xingwu]

The site is well organized and the information flows smoothly, nice job.

[tonyhart7]

but what is the cons here???? anything you mention about the pros, there must be cost to make right??

after fast skimming it, I found its gonna be hard to separate concern when build interactive UI

[progx]

It is a simple lib for simple things. If you need more, there exists "hundreds" of frameworks for more.

[gavmor]

Slick looking website, novel and relatively intuitive DSL, solid documentation!

Parsing the playground demo was a fun scavenger hunt! Too fun... it took me several minutes to find `(coins += income)` at the line break. For me, it's difficult to scan for "code" that's in-lined as strings. That <progress/> eval, especially, is a doozy!

> Use this [eval] directive sparingly, prefer alternative directives for better maintainability and security. This directive is intended for edge cases.

Oh, and yet *eval is the heart and soul of the demo? In fact, it looks like the principal action--creating buildings--is performed by... the progress bar? That's low-cohesion and high-coupling if I've ever seen it.

I would want to know: what are the Mizu ways of modularizing code to increase cohesion and decrease coupling?

Anyways, thanks for sharing and congrats on launching.

[CharlieDigital]

    > I would want to know: what are the Mizu ways of modularizing code to increase cohesion and decrease coupling?

Ostensibly exactly what you would do with JavaScript.

Write a class or function closure similar to Vue composables.

It's not really the framework or library's job of making your code more modular; that's your job by writing good code.

[lowlighter]

Yeah the playground is intended to show many directives to display the capabilities, but I wouldn't recommend making complex apps entirely with the iife version. It's mostly intended for templating (like conditional, iterations, htmx-like op).

The ESM version is better suited for small dynamic apps as you can handle context in a better way, and define helper functions rather than declaring them in a html attribute. It makes the code more readable too and this how you'd be able to achieve a more cohesive app.

As for the eval, it's true the doc advertise against, but maybe I was a bit too harsh about it. The reasoning behind avoiding it is the same as "eval()" in js. It's kind of a "god mode" (like you could do *eval="this.remove()") and it may mess up your final rendering as some internal reference may not be properly cleared if you do niche stuff. If you know what you're doing there's no particular issue with it

[replwoacause]

https://mavo.io is another similar idea

[alexchamberlain]

The licence seems messed up. You can opt to use an MIT licence, but only if you're noncommercial or you pay. The MIT licence explicitly states that the software is provided free of charge, and can be sublicensed, so anyone with an MIT copy, can give it away for free.

[wccrawford]

That alone makes me not want to use it. Licensing has to be clean and clear for it to have any chance with me.

[benatkin]

It’s valid. It’s not the MIT license, but it’s not messed up or confused either. It’s just an unusual license.

It means you don’t have to GPL your own code while your project is non-commercial and you aren’t paying for it. If you decided to make your project comercial you could migrate away from it or pay for it. It also seems to have a loophole if you interpret it a certain way and transfer it, because the person agreeing and the person receiving it under the MIT license would be different people.

[lowlighter]

Yeah maybe I'll look into a simpler licensing as it may indeed be confusing and just drop the requirement, it's not like I really planned to make money with it anyways.

While I doubt this project will ever reach the popularity of projects such as docker, terraform, mondogb, wordpress, corejs, and many others, I'd like to avoid having issues that they encountered later due to their licensing.

Basically having companies that could afford to contribute and help maintainers but that choose to not do it just for pure greed, while keeping it free for everyone else that continue to make open project or just non-profit/personal use case.

As I'm no legal expert, the intention may not have been very clear in the wording though

[arunaugustine]

On the bright side, you need to pay only $1+, if you are using it commercially. Seems a reasonable ask and a nice way to support the development. Interesting approach to licensing indeed, but I wouldn't call it messed up. It's just new.

[jraph]

Yeah, you probably don't want to license under MIT for proprietary use cases. You could take inspiration from the Qt project for how they do this.

It takes one "non-commercial" project to release their code and people can use the MIT licensed version without restriction.

The concept of non-commercial itself is shady: what if someone releases something non commercially, and then someone else uses it commercially?

You probably want to get rid of this, it's complex to understand and to apply. You could have:

- an AGPLv3 version that open source projects will be able to use (commercially or not, there are many successful commercial open source projects)

- a custom proprietary license that someone can use only if they pay, and de facto their project cannot be open source

Of course, this also means that your code can't be used by projects that want to be released under the MIT license. People will need to release under the AGPLv3.

[simonw]

Yeah, that's a mess. The MIT license thing with additional limits just doesn't make sense.

I suggest licensing under both AGPL and an existing, documented source-available license - maybe BUSL? https://en.wikipedia.org/wiki/Business_Source_License

[err4nt]

I wish it didn't require authors to practice doing the wrong thing (writing invalid HTML) for to use the tool.

Authors are free to either create any data-* attributes they wish for any purpose, so long as the custom attributes are prefixed with "data-".

Authors are also free to create any (valid) HTML custom element, and to invent custom attributes for those elements.

But this appears to require authors to write invalid HTML.

[zamalek]

You should be able to use qnames (foo:bar) for attributes, I think? The problem with data-* is that it's misuse, template directives aren't really data. E.g. something might actually use data-if, which would probably collide with a template directive.

[beders]

We've been down this road before many times.

On adoption things are simple and clean.

Then your product becomes more complicated and your requirements for data handling outgrow what a tool like mizu can offer.

Then you are facing a choice: Redo everything in a more scalable and expensive (as in dev training, qe needs) framework/library or stick with that you have?

Choose carefully.

[lowlighter]

I think rather the issue being new library popping up is more about choosing the right tool for the right project.

If you know that your project is going to be small-scaled (a MVP or POC, a blog, a UI for your home lab, a static website, etc.) then mizu and tools alike may be a good choice.

If you know that you eventually want to have thousands of customers, with hundreds of collaborators, then it might indeed be not the best fit. Going with a more "common" framework like the big name React and Vue is probably better.

Web dev nowadays offer a wide range of application, so everyone needs is different so a one-size-fits-all framework/library is almost impossible to achieve in my opinion

[jchw]

My personal first experience with this was Riot.js. Ultimately, I still enjoyed using it, but writing large applications in micro frameworks is hard: it feels like either the micro framework grows substantially and starts to lose its original appeal, or your application grows framework-like limbs and suddenly the appeal of using a micro-framework is somewhat diminished.

I would guess the only real way out is to always carefully constrain your scope and keep your application as simple as possible. Easier said than done...

[spankalee]

Do you have specific reasons why this would be true of Mizu?

It's certainly possible to build sufficiently rich data handling and modularization into HTML, and to make seamless integration between HTML and components and JS.

The fact that plain HTML can be extended with custom elements already means that just about any HTML system can be decomposed so that the the most complex things are encapsulated behind components.

[gwbas1c]

> In summary, mizu.js is free for open-source and non-commercial projects, while a small contribution is required for commercial closed-source projects to support its development.

That's... weird.

I've evaluated front-end frameworks in the past and considered both free (open source and no cost) against commercial. I can't explain why, but the mandatory donation for commercial use just rubs me the wrong way.

(And don't get me wrong, I've published my own basic HTML templating library here: https://www.npmjs.com/package/pogon.html)

Perhaps I can explain it this way: If I'm doing a hobby/learning project, there's no obstacle to using Mizu. But, if I'm a rank-and-file employee, experimenting, setting up the $1 / month donation is actually a huge obstacle. It's not the cost, it's the actual act of handling money. Furthermore, Mizu will need a lot of paying customers for the monthly donations to actually pay for anything substantial.

Personally, I would think more carefully about how to derive income from Mizu.

[gavmor]

Right, $1 / month is not worth the overhead to enterprise customers. My understanding is that many would rather find a $10,000 / month solution that has all the bells and whistles--and a support contract!

Is there an uncanny valley between free and enterprise--or is that actually a fertile long tail?