DEV Community: lowlighter 🦑

Supercharge your HTML with mizu.js!

lowlighter 🦑 — Tue, 03 Dec 2024 18:15:00 +0000

Looking to build interactive web apps with ultimate flexibility and adaptability?

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!

Why yet another JavaScript templating library?
I get your concern, but hear me out!

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!

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!

Make naked websites look great with matcha.css!

lowlighter 🦑 — Fri, 24 May 2024 09:11:00 +0000

Have you ever contemplated the bareness of starting from a "blank page" when beginning a new web project?

index.html
Notice the lack of any styling or custom attributes.



<html>
  <body>
    <h1>Hello world!</h1>
    <p>
      This is my new project, and it's still under construction.
      Please be indulgent 😊
    </p>
    <p>
      Also, check out my work on <a href="https://github.com/octocat">GitHub</a>!
    </p>
    <blockquote>
      <p>
        Imagination is more important than knowledge
      </p>
      <cite>Albert Einstein</cite>
    </blockquote>
    <menu>
      <li>Home</li>
      <li>
        About me
        <menu>
          <li>My works</li>
          <li>My passions</li>
        </menu>
      </li>
      <li>Contact</li>
    </menu>
    <form>
      <h2>Contact me</h2>
      <label>
        Your email:
        <input type="email" name="email" placeholder="Your email" required>
      </label>
      <label>
        Your message:
        <small>255 characters max</small>
        <textarea name="message" placeholder="Your message" required></textarea>
      </label>
      <button type="submit">Send</button>
    </form>
  </body>
</html>

Ouch! If you showed that to your friends while claiming you're a web developer, they would start questioning what you're really doing...

Default browser stylesheets are usually pretty bare-bones, and it can be frustrating to not have something "visually nice" when you're prototyping apps, generating static HTML pages, Markdown-generated documents, etc., and don't want to delve into CSS intricacies too early.

Good news! I have something perfect for you: matcha.css!

Just add the following into your document and see the magic happen:



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

Without really doing anything, we got a page that respects user preferences on light/dark mode, nice fonts and proper spacing, our <menu> actually looks like a menu, and our <form> is also pretty nice with even "mandatory field" indicators for required inputs.

All of that without any build steps, JavaScript, configuration, or refactoring.

It's because matcha.css uses semantic styling. For example, it assumes that <menu> nested in another <menu> should result in a submenu, while a <label><input required></label> should clarify to the user that the input is mandatory.

There are a few more "drop-in" CSS libraries out there, but I believe this is the most complete one as it provides additional modern styles out-of-the-box like syntax highlighting, simple layouts, utility classes, etc.

matcha.css is also easily customizable (it does not have any !important rules, and even provide a helper to create custom builds) and while being also reversible (if you ever decide to migrate out, just remove the stylesheet).

And last but not least, it's totally free and open-source!

lowlighter / matcha

🍵 Drop-in semantic styling library in pure CSS. Highly customizable and perfect for simple websites and prototyping web apps!

Checkout matcha.mizu.sh for a full overview!

Using GitHub Codespaces with VNC/flexbox to create Pokémon maps from a web browser

lowlighter 🦑 — Thu, 20 Jan 2022 18:55:10 +0000

Hi there 👋 !

I'm currently working on a cool project, 🌺 Gracidea, which is an animated Pokémon live web map aiming to recreate the whole Pokémon world while being accessible directly from your browser:

I use a combination of several technologies, like deno, pixi.js, vercel.com and Tiled map editor along additional other tools. Some of these, like Tiled, are graphical desktop apps so they need to be installed first.

Which made wonder, what if it was possible to provide a graphic environment to access desktop apps and edit maps directly from a web browser... 🤔 ?

And it is 🥳 !

If you don't know, GitHub offers codespaces which lets you spawn a web-accessible docker instance from a repository with VS Code pre-installed. However, not many people know that it is actually possible to configure the dockerfile through the .devcontainer folder of said repository.

ℹ️ Note: Seems that this feature is in closed beta for users accounts

After playing a bit with Microsoft's vscode-dev-containers' lightweight desktop I achieved to configure vnc and flexbox (the provided desktop env) to spawn a full-screen instance of Tiled!

Below's a preview of the whole thing, in Firefox (yes, everything is happening in the browser !😮)

So yeah, basically all you need to setup this project now is just a web browser, no headaches caused by "but it works on my machine 😵 !"

If you're interested in the required code to make this works, it is available here!

Thanks for reading 💕 !

Discover your GitHub ranking with Metrics Insights!

lowlighter 🦑 — Mon, 19 Apr 2021 17:11:14 +0000

Ever wondered how high is ranked your most starred/forked repository across all GitHub? Or whether if you're one of most followed user account 🙂 ?

Well, this is possible thanks to Metrics Insights!

There's also a few additional data, like the number of bytes you've written for each languages you used up until now!

Best of it is that you can use Metrics Insights in your browser without any account login nor cookies!

🤔 How does it work though?

I'm currently working on Metrics, a project designed to gather data that you can then render as SVG to embed on your GitHub user profile, like below:

Currently, there's hundreds of options, including 4 templates and 30 plugins, one of them being the 🏆 Achievements one:

As you can see, some of them include ranking. You may wonder of these are computed? Well it's actually a lot simpler that it may looks, using GitHub GraphQL API and Puppeteer.

The trick is to fetch the number of followers, created repositories of said user, along with their most starred repository and most forked repository.

Then using search GitHub GraphQL API, we can count how many users and repositories are above using the following query (replacing each $ prefixed values with what we found earlier):

query AchievementsRanking {
  repo_rank:search(query: "stars:>$stars", type: REPOSITORY, first: 0) {
    repositoryCount
  }
  user_rank:search(query: "followers:>$followers", type: USER, first: 0) {
    userCount
  }
  forks_rank:search(query: "forks:>$forks", type: REPOSITORY, first: 0) {
    repositoryCount
  }
  created_rank:search(query: "repos:>$created", type: USER, first: 0) {
    userCount
  }
}

As you can see, we only retrieve the total count of each categorie, we don't even try to fetch any content. So basically, if an user has 100 followers and user_rank.userCount send back 999 users, we can deduce that user is 1000^th (999+1) since 999 users has more followers. We do the same for each categorie.

One thing to note is that GitHub API may return incomplete count below some thresholds as there's too many results to compute for even GitHub to handle it. But if you have created a respository at least once, or having a repository which has been starred 5+ times or forked 1+ time or if you have 3+ followers, you can compete within each categorie 😃 !

I guess it also means that there's a lot of inactive users and unused account, so if you're somewhat active on GitHub you'll be able to see your stats pretty easily with this tool.

Since it's not possible to estimate how many repositories and users exists through GitHub's own API, you may wonder how I got total repositories and users count?

Well, actually these are displayed on GitHub search:

This is why we needed puppeteer 🙂 We just crawl a few times (displayed stats is random between users, repositories and issues) and extract these. Once we got each categorie at least once, no more need for puppeteer, we're ready to go!

If you're interested, don't hesitate to take a look at this project source code and support it. There's even a plugin to update your profile readme with your latest post from dev.to!

lowlighter / metrics

📊 An infographics generator with 30+ plugins and 300+ options to display stats about your GitHub account and render them as SVG, Markdown, PDF or JSON!

You can provide some feedback like bug reports and suggestion for this feature on GitHub discussions 🙂

Thanks a lot for reading, and don't hesitate to share your scores in comments section!

One last bonus: can you guess who is the most followed GitHub user? Click here to know!

Metrics v3.0, the ultimate tool to pimp your GitHub profile!

lowlighter 🦑 — Mon, 04 Jan 2021 17:24:35 +0000

Metrics is an extensive SVG images generator plugged with various APIs (GitHub, Twitter, Spotify, ...) to embed awesome informations about your daily coding routine on your profile!

It's highly configurable with multiple templates and plugins, and for optimal pragmatism, it uses transparency with a color font which works on both light/dark modes, so you'll never offend the eyes of your visitors anymore!

🧩 Build your dream profile now!

Metrics works with a plugin system to make it highly customizable.

Want to refresh a bit your profile and flex a bit about your 2-days commit streak? Well, why not add an i s o m e t r i c calendar to it?

With metrics you can display a lot useless facts about you. You'll be able to know how many datacenters you're filling up with the /node_modules you inadvertently pushed because you forgot to .gitignore it, your favorite license (very interesting right?) or even the number of lines of code you've published on GitHib. Of course, there are also more "traditional" stats available in other sections, indicating your internet clout 😎

You can also display your war medals for each framework you've starred in GitHub topics:

And show that you're a true polyglot who knows how to say "hello world" in many languages:

Then you can use smooth charts to show everyone that you've got an incredibly unhealthy sleep cycle with all your stacked commits at 2 a.m.:

Web devs can prove that they're building optimized websites, despite including more JavaScript libs than the number of observable atoms in the universe:

And you can show that you're a true scrum expert by adding your projects progress, even if you never finish them anyway because you get bored of them way before:

And if you're a twitter addict, you can display your latest tweets:

Finally, you can show the world that you have awesome music tastes:

And last but not least, some of what has been presented here can also be used for repositories! A nice addition for your readmes!

If you're some who is spreading love everywhere by supporting passionate developers by starring their projects, you can display it 💕!

A little bonus for all dev.to writers here, they can also display their recent posts with this!

There's a few more features available, so be sure to check it out!

lowlighter / metrics

📊 An infographics generator with 30+ plugins and 300+ options to display stats about your GitHub account and render them as SVG, Markdown, PDF or JSON!

Thanks again for reading until the end!

PS: New ideas and contributions are welcome!

Downtime, a simple uptime/response time monitor using GitHub actions

lowlighter 🦑 — Sat, 12 Dec 2020 12:20:00 +0000

Hi there 👋,

This is a small presentation of one of my recent projects : Downtime, an uptime/response time monitor.

It generates SVG badges that you can use anywhere to display whether your server is up or not :

The real badges are actually transparents, rendering nice on both light/dark mode

📦 How to setup (< 2min) ?

It is based on the Keep It Simple Stupid philosophy, so it's super-straightforward :

0: Fork the repository
1: Edit the config.yml to add your hosts

The config.yml is just a list of domain/server/ip/port you want to monitor :

hosts:
  # Check if google.com is up
  - name: google.com
    title: Google

  # Check if a given url is up
  - name: github.com/lowlighter/downtime
    title: Downtime repository

  # Test an ip/domain with port using ncat (any protocol)
  - name: "8.8.8.8"
    title: Google DNS
    port: 53
    use: ncat

2: (optional) You can also enable GitHub pages and get a webpage with all your servers status !

⚙️ How does it works ?

A GitHub action workflow is ran each 5 minutes, testing connections with the hosts you specified in config.yml. It can either use curl (for HTTP/HTTPS) or ncat/telnet (any protocol). It records if target is reachable and its response time.

Since it use the default GITHUB_TOKEN to update connection results, there is no need to create an additional personal token, keeping your account safe.

You can also set the repository private, keeping only the GitHub pages and the badges to embed elsewhere.

✨ Inspiration

This has been inspired a lot by upptime, but I didn't liked the fact you needed a token with a lot of permissions (especially since the workflow update itself so you need to put a lot of trust in maintainers) and that you couldn't get a status badge to tell whether your server is up or not.

Thanks for reading !
If you like generated SVG images, you may also checkout GitHub metrics !

Rendering the commit calendar in isometric view

lowlighter 🦑 — Tue, 03 Nov 2020 19:07:12 +0000

Recently, I found a browser extension called isometric-contributions which displays the GitHub commit calendar in an isometric view. It looked quite neat, but it can't be used as a standalone...

So I decided to make a similar render as part of my metrics plugins suite, which executes itself either as a GitHub action or as a NodeJS server.

Below is the final render, generated with about 80 lines of code :

You can test it with your own GitHub account here by checking "Isometric commit calendar" option !

🔧 Under the hood

Using GitHub GraphQL API, it retrieves the contributionCalendar from the contributionsCollection.

To ensure the last row get a full week, the start date queried is always set to a monday.

Then, it iterates a first time over the contribution calendar to find the highest number of contributions in a single day, the current commits streak and the average commits per day.

Then, it iterates once again over the calendar, but this time to generate the SVG.

Each day creates a new isometric rectangle, with its height depending on the contributionCount of said day scaled to the highest count found previously.

Color is already given by GitHub API (which allows easier supports for the Haloween theme), though it adds brightness filters to simulate shadows and make render nicer.

Pretty simple, no 😁 ?

Using GitHub Explore to find hidden gems

lowlighter 🦑 — Mon, 02 Nov 2020 18:35:00 +0000

I really like to see what fellow developpers out there built. From famous frameworks to small side projects, I always find it interesting and impressive what awesome stuff people are making.

Recently, I discovered the GitHub explore tab, that you may or not know (personally, I didn't even knew it existed). It's located at the end of the main navbar.

Here's what it looks like :

Basically, it'll provide a "news feed" with projects and issues you may be interested in, along with some apps that you could introduce in you workflow and GitHub news.

To build your feed, you'll need to select a few subjects from Topics tab, which is also probably the most useful section. There are a lot of categories available, from general computer sciences stuff, to specific programming languages or even frameworks.

You can also browse directly a topic. By default it's sorted by stars, but you can change the criteria and find some hidden gems if you're lucky... Pretty neat !

The Collections tab is also pretty cool as it contains a curated list of projects related to a more generic subject.

You should definitely check it out this feature if you got some spare time !

Embellish your GitHub readme profile with 20+ metrics, PageSpeed stats, music you've listened to and more !

lowlighter 🦑 — Tue, 27 Oct 2020 00:04:44 +0000

So it's been a while since GitHub introduced its profile readme feature which lets you customize your user profile. Since then, a lot of people have been creative with it, and have been developping on components like github-readme-stats, github-profile-trophy or waka-readme-stats.

Today, I'm introducing metrics, a set of various plugins that generates SVG images that you can embed in your user profile to make it even more prettier ! It can be setup either as a GitHub action or as a web server.

📊 20+ metrics about you !

The main plugin lets you display your account metrics, listed in three categories : Activity, Community and Repositories. Some common stats are included like number of commits, stars, contributions, ... But also a few more exotic ones like your prefered license !

You can configure it to hide some parts if you find it too cluttered. A lot of numbers can be intimidating for some people (unless it's on a paycheck haha).

Also, generated SVGs are transparents with a color font that blends well with both light and dark mode, so your visitors will be able to see it whichever side they are !

🚀 Faster than light with the PageSpeed plugin

If you have a website linked to your account, you can also display its PageSpeed performance scores and shows that you've mastered the web.

🎼 Show what you listen to with the music plugin

If you're using Apple Music or Spotify to listen music, you can use the Music plugin to display randomly music tracks from one of your favorite playlist. You'll just need to provide its embed url.

If you're brave enough to create a Spotify token, it's possible to display the track you recently listened to instead.

🎨 Reveal the artist in you with templates

The generated SVGs are rendered through EJS, which means you can actually use HTML, CSS and JS to template your metrics from the data gathered through the various GitHub APIs and plugins.

For instance, I made a more nerdy alternative template based on an unix terminal :

But if you're comfortable enough with web, you'll be fine making your own template. Don't hesitate to share it if you made something awesome !

🦑 Intrigued ?

There are even more at lowlighter/metrics, including documentation and source code. Try it now at metrics.lecoq.io !

Thanks for reading !