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!
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.
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>
Via https://github.com/lowlighter/mizu?tab=readme-ov-file#-licen...
EDIT: never mind the license killed it for me. Cool innovation but unusable with its AGPLv3 license.
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
“Water” is as good a name as any other. Congrats on your work, I look forward to testing it out this weekend!
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.
Caught 1 typo and 1 broken link on the site in case you'd like to fix: https://triplechecker.com/s/477573/mizu.sh
Rather than using a v- prefix like vue has, mizu uses *, but it's essentially the same.
All in all, I feel like it's still pretty close to what vue offers, at least when you plug it directly to your html page without passing by the component/composition way of writing vue.
I took a lot from vue (maybe more petite-vue at this point) and alpine to make mizu actually
after fast skimming it, I found its gonna be hard to separate concern when build interactive UI
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.
> I would want to know: what are the Mizu ways of modularizing code to increase cohesion and decrease coupling?
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.
I guess what's not immediately clear to me is what's in scope for eg eval. I'll have to dig into the docs more than I have.
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
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.
Can't tell you how many developers I run into who presume anything source-available is fair game, install it with their dependency manager, and move on without even reading the license.
Could you imagine if software companies required legal to review every change to `package.json` or `requirements.txt`?
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
For a lawyer's opinion on those two things, see:
https://writing.kemitchell.com/2022/01/21/MIT-for-Noncommerc...
https://writing.kemitchell.com/2023/09/10/Two-Kinds-Dual-Lic...
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.
I suggest licensing under both AGPL and an existing, documented source-available license - maybe BUSL? https://en.wikipedia.org/wiki/Business_Source_License
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.
Here's what the HTML spec[1] says about data-* attributes:
Custom data attributes are intended to store custom data, state, annotations, and similar, private to the page or application, for which there are no more appropriate attributes or elements.
1: https://html.spec.whatwg.org/multipage/dom.html#embedding-cu...
It'll kind of solve the previous commenter concerns about with writing invalid html. While namespaces are more a xml thing, there are probably many benefits to this approach like querying all attributes from the namespace at once too.
I'll keep this in mind for future iterations!
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.
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
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...
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.
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.
Is there an uncanny valley between free and enterprise--or is that actually a fertile long tail?
Even small customers, too. Think of an early startup or small company trying to decide what their stack will be.
The hassle of a $1 / month donation is "more work" than spending $250 / seat for a 1-year contract with some amount of support.
I need to really love it to do so (and in the one instance I did) I need to have been able to use it in that corporate setting before that point.
Yeah, actual components like you’d encounter with any modern framework/library like React.
It has some nuances but they are pretty much real components, and I was able to make some pretty advanced functionality in an otherwise typical spaghetti code disaster.
Even wrote unit tests for it. People were in disbelief any of this was even possible.
Turns out that while modern patterns and tooling go a long way, they you still need to put effort into making quality software of any kind.
Apparently, they even have a v4 reboot: https://www.tko.io/
Maybe my memory is that bad now in my old(er) age. But at that point in 2015, React had been a thing for about 2 years already. Ember had components even earlier than that in 2011/2012. Using components generally was a pretty well-accepted pattern from my recollection. The wars between the frameworks were all centered around render performance rather than APIs (i.e. which virtual DOM was best? do you even need a virtual DOM? etc.)
Not taking anything away from knockout per se, more just gut checking my own understanding/remembrance of that dark age.
https://react.email/docs/introduction
It helps me ship faster when I use the same stack everywhere. I even ported my background task library to TypeScript so to keep the stack the same:
[1]: https://github.com/alexandremcosta/alexandremcosta.github.io...
Markup should only contain content and presentation. If it needs to be templated, then that's best done using a separate syntax.
If we need functionality, then that's the domain of JavaScript and programming languages.
We learned the importance of semantic HTML decades ago when we stopped using style elements and left this exclusively to CSS.
Separation of concerns is important. Yet modern frameworks insist on blurring these lines for some reason, and we end up with bastardized syntax, writing JS inline in attribute values, and cramming dozens of utility classes to style a single element (Tailwind is an abomination).
I don't mind frameworks that embrace components while keeping this separation clear. I think Svelte does a pretty good job at that, or at least it does a good job at hiding the magic it does to achieve this illusion from the developer. But from my limited exposure to Vue, React and Angular, these are not frameworks we should take inspiration from, and mizu looks even more jarring than those.
My issue is not whether the custom props are rendered into the DOM, but about the developer experience. Svelte, for example, has separate templating syntax and generally tries to keep things isolated, even if it's ultimately all compiled to JS.
The DX on React is quite nice. You had to do a bit of extra stuff to squeeze out a bit more performance by memoing stuff, but that's finally supposed to be fixed in React 19. And it's not like that perf was free if you did everything by hand anyway, that just required you to handroll clever batch DOM updates.
However, IMHO people have gone overboard with layering in so many places creating spaghetti projects that makes troubleshooting feel like goto riddled Basic of old.
In my view Vue's v-if / v-for / v-else is solidly for binding the viewmodel semantics, trying to separate it would require adding id's or some other way of connecting data to view production for no extra reason other than to specify that a list should be duplicated elements?
Wrote a small Vue page/app recently and this pragmatism really helped keep is small yet quite clean, HTML(with some small pieces of Vue markup), CSS and JS in each place. Would the project need to grow it'd be fairly easy to separate parts out into components but there wasn't even a need due to the small size.
Specialization is another aspect. Take this example from the mizu docs:
<div %http="https://example.com">
There are thousands of these questions and possible limitations and pitfalls that just wouldn't exist if the library didn't try to reinvent JavaScript in HTML. Just use the right tool for the job that is already specialized for what you're trying to do, and your task will be much easier.
BTW, I don't mind having components that contain JS, CSS and HTML in the same file. Svelte does this and I enjoyed using it. My problem is when these are mixed, or when CSS is entirely abandoned in favor of thousands of micro utility classes like Tailwind does.