How liz-origin/elizabeth works
This repo is a web framework + compiler/transpiler + dev server + client runtime built on Bun. It introduces a custom component syntax (.liz in examples; README mentions .eliz but tree shows .liz) that transpiles to JS/TS with f() calls, supports SSR, and implements Islands Architecture (partial hydration) with a small client runtime (useState, event handling).
• Toolchain pipeline (CLI → transpile → bundle/run dev server)
• Runtime architecture (server SSR → HTML + island markers/scripts → browser hydration per-island)
• Key modules (transpiler, router, server, core render, client runtime)
• Example apps (as consumers) and generated cache artifacts (.elizabeth/cache/*.tsx)
File structure: what’s architecturally meaningful
Top-level:
• src/ = framework implementation
• bin/elizabeth = CLI entrypoint wrapper
• examples/* = consumer projects demonstrating usage
• bun.lock, package.json, tsconfig.json = Bun/TS build + runtime configuration
Within src/:
• src/cli.ts — CLI behavior (dev/build/etc. as implied)
• src/transpile.ts — the compiler/transpiler: .liz → JS/TS/TSX using f()
• src/core.ts — core f() + render() (SSR output, island script injection likely happens here or adjacent)
• src/framework/server.ts — dev server (Bun HTTP + file watching)
• src/framework/router.ts — file-based routing (maps app/**/index.liz to URLs)
• src/framework/client.ts — browser runtime (hydration + useState)
• src/index.tsx / src/framework/* / src/index.tsx — public API surface + exports
Examples indicate ecosystem integration:
• examples/liz-tw/ includes tailwind.config.js, build-tailwind.ts → external build step feeding CSS into the app.
The README explicitly defines the pipeline:
useState state management within islands
• Build/Dev pipeline (tooling): CLI + transpiler + dev server + cache output
• Runtime (request/response + hydration): server SSR + browser hydration
Core Runtime – Server (src/core.ts render + f())
Browser-side
Client Runtime (src/framework/client.ts) (hydration + hooks like useState)
7. Islands Loader / Hydration Scripts (conceptual component: “per-island bundles / inline scripts”)
Artifacts / Inputs
Transpile Cache (.elizabeth/cache/*.tsx) (derived output)
10. (Optional) Tailwind Build Step (for examples/liz-tw: build-tailwind.ts → CSS output)
You want at least these directional flows:
Dev/build time
• Developer → CLI (bun run dev / elizabeth)
• CLI → Dev Server
• Dev Server ↔ Router (resolve URL ↔ file path)
• Dev Server → Transpiler (compile .liz when requested or on change)
• Transpiler → .elizabeth/cache/*.tsx (write derived TSX/TS modules)
• Dev Server → Core render() (SSR renders compiled components)
Request-time (server)
• Browser HTTP GET /route → Dev Server
• Dev Server → Router → identifies app/.../index.liz
• Dev Server → Transpiler (ensure compiled module available)
• Dev Server → Core render(vdom) → returns:
• Static HTML
• Island markers / island manifest
• Hydration script references (per island)
Client-time (browser)
• Browser receives HTML → displays static content immediately
• Browser loads Client Runtime + per-island scripts
• Client Runtime hydrates only detected islands
• useState works inside hydrated islands (no hydration = no state)
Styling flows
• .css and *.module.css imported by .liz:
• As inputs to transpilation/build
• Tailwind (example): build-tailwind.ts → generated CSS → linked in HTML
Architectural patterns explicitly
Callouts/labels for:
• Islands Architecture / Partial Hydration
• File-based routing (app/about/index.liz → /about)
• Compiler/transpiler stage (custom syntax → JS/TSX with f())
• SSR first (HTML returned from render())
• Client runtime minimalism (only islands hydrate)
Technologies (don’t overdo, but be explicit)
• Bun runtime on server/tooling side
• TypeScript (src is TS; generated cache is TSX)
• Browser side runtime
• Tailwind only as an optional external pipeline in the example(s)
• CSS Modules support path (module import → hashed class mapping)