zilk

light & flexible web framework

[!WARNING]
zilk is actively being built out. It's functional and used on m4r.sh and mfers.lol, but it's not ready for public adoption.

Overview

zilk is an attempt to simplify web development without sacrificing freedom. Like silk, it should be flexible, almost invisible, and structurally sound.

It's split into two libraries:

zilk (runtime)

• Render HTML: DOM + SSR tagged template rendering from uhtml and uhtml-ssr
• Hydration: class-based event handlers from wicked-elements
• Navigation: on-page navigation helper (code started as a fork from navaid)
• Router: Fetch handler to serve SSR Responses from Bun, Node, or Workers

zilker (build tool)

• File-based: Intuitive project organization
• Powered by Bun: Fast by default
• Plugin-friendly: Custom dev experience and build settings

Usage

Environment Setup

1. Install [BunJS]
2. Install syntax highlighter [VSCode] [TextMate Grammar]
3. Install zilker globally: bun i -g zilker
4. Open a new folder and run zilker setup
5. Edit with zilker dev
6. Build for prod with zilker build <target?>

Example UI Component

1. Render function (HTML)
2. handlers (JS)
3. style (CSS)

At build time, each export is handled differently. All handlers are bundled into a hydration script, all styles are bundled into a CSS stylesheet, and the render functions are bundled with the browser-side router. Server-side rendering only requires the render function, which is the default export.

// views/Example.js
import { html, css, classify } from 'zilk'

const { TITLE, BUTTON } = classify('Example')

// 1. Render function (used for SSR and browser rendering)
export default ({
  title="Default Title",
  btn_href="https://github.com/m4r-sh/zilk",
  btn_label="Zilk Docs"
}={}) => html`
  <h1 class=${TITLE}>${title}</h1>
  <a class=${BUTTON} href=${btn_href}>
    <span class=${BUTTON.LABEL}>
      ${btn_label}
    </span>
  </a>
`

// 2. Class-based event handlers, auto-attached on browser
export let handlers = {
  [BUTTON]: {
    init(){
      console.log('Runs once per element')
    },
    onclick(event){
      console.log('Click event')
    }
  }
}

// 3. Class-based CSS styles - extracted at build time
export let style = () => css`
  .${TITLE}{
    font-size: 3rem;
    color: #555;
  }
  .${BUTTON}{
    padding: 1rem 0.5rem;
    background: #000;
  }
  .${BUTTON.LABEL}{
    color: #fff;
  }
`

OUTER // "Nav-Button__OUTER" LABEL // "Nav-Button__LABEL"

Exports

zilk/dom (3.8 kB)

main export from zilk for rendering on the browser

zilk/ssr (2.2 kB)

main export from zilk for server-side rendering on Bun, Workers, NodeJS

zilk/hydrate (1.8 kB)

Ideal exports for generating a hydration script (hydrate.js)

zilk/nav (1.6 kB)

Ideal export for generating a client-side routing script (nav.js)

zilk/fetch (3.2 kB)

Ideal export for generating a server-side request handler

Credits

The performance of zilk is largely due to @WebReflection's incredible work on uhtml, wicked-elements, and other top-tier JS libraries.

Credit to navaid for simple client-side navigation logic, and to itty-router for minimal route matching.

The developer experience is inspired by Next.js, Svelte, Astro, and other great tools I've used over the years. The JavaScript ecosystem is bustling with innovation, but the overwhelming complexity makes it difficult to leverage these tools without getting stuck.