htmx kanban

## TL;DR You will build a fully functional, live-updating kanban board using **htmx 2.0.10**, **TypeScript 6.0.3**, **Express 5.2.1**, and **better-sqlite3 12.9.0** on **Node.js 24 LTS** — without a single line of client-side JavaScript framework code. The server returns HTML fragments, htmx swaps them into the DOM, and **Server-Sent Events** push updates to every connected browser when any user moves a card. Total app: roughly 200 lines of TypeScript across four source files, runnable in 15 minutes. This htmx tutorial focuses on TypeScript and Express because the existing 2026 ecosystem leans heavily toward Python/Flask or Go demos. If your team already runs Node.js, this is the stack you want — type-safe routes returning hypermedia, SSE for live updates without WebSockets, and SQLite so you don't need to provision a database to follow along. Every version below is pinned and verified against the official registry on the day this was written. ## What you will learn - How to scaffold a typed htmx + Express 5 project with `tsx` for fast feedback - How to model a kanban board in SQLite with `better-sqlite3` synchronous transactions - How to render initial HTML and **HTML fragments** for `hx-get`, `hx-post`, `hx-put`, and `hx-delete` - How to use **`hx-swap-oob`** (out-of-band swaps) to update multiple unrelated DOM regions from a single response - How to add live multi-user updates using the **htmx SSE extension** and the native `EventSource` API - How to harden routes with **server-side validation**, structured error fragments, and an htmx-aware error path - How to verify everything with `curl` so you trust the wire format before the browser ever opens ## Prerequisites | Tool | Version | Reason | |---|---|---| | Node.js | 24.15.0 (Active LTS, April 2026)[^1] | Express 5 needs Node 18+; LTS gets security patches through April 2028 | | npm | 10.x (bundled with Node 24) | Package install | | SQLite | bundled in `better-sqlite3` 12.9.0 | No separate install needed | | A modern browser | Chrome 120+ / Firefox 128+ / Safari 17+ | Native `EventSource` and modern CSS Grid | This tutorial does not use Docker. SQLite gives you a zero-setup database, and `better-sqlite3` ships its own SQLite — pull the repo, `npm install`, run, done. ## Step 1 — Scaffold the project Create the directory and the bare TypeScript project. We use `tsx` (a thin esbuild wrapper) instead of `ts-node` because it runs ESM natively and is dramatically faster for the dev loop.[^2] ```bash mkdir htmx-kanban && cd htmx-kanban npm init -y npm pkg set type=module npm install express@5.2.1 better-sqlite3@12.9.0 npm install -D typescript@6.0.3 tsx@4.21.0 @types/node@24.0.0 @types/express@5.0.6 @types/better-sqlite3@7.6.13 ``` Pin versions exactly. The 2026 npm ecosystem moves fast, and a tutorial that breaks the moment a transitive `^` major-bumps is not a tutorial. If you read this later than May 2026, run `npm view version` for each line above and either pin to those values or update consciously. Create `tsconfig.json`: ```json { "compilerOptions": { "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext", "lib": ["ES2023"], "outDir": "dist", "strict": true, "noUncheckedIndexedAccess": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*.ts"] } ``` `noUncheckedIndexedAccess` is the single most useful strict flag for this codebase — it forces you to handle missing rows from SQLite queries explicitly. Add scripts to `package.json`: ```json { "scripts": { "dev": "tsx watch src/server.ts", "build": "tsc", "start": "node dist/server.js" } } ``` Create the source folders: `mkdir -p src public`. ## Step 2 — Model the kanban board in SQLite A kanban board is two tables: columns and cards. We hard-code the three columns (`todo`, `doing`, `done`) so we don't have to build column-management UI, and we keep cards in a single table with a `column` discriminator and a `sort_order` integer. Create `src/db.ts`: ```ts import Database from "better-sqlite3"; export type Column = "todo" | "doing" | "done"; export interface Card { id: number; title: string; column: Column; sort_order: number; created_at: string; } const db = new Database("kanban.db"); db.pragma("journal_mode = WAL"); db.pragma("foreign_keys = ON"); db.exec(` CREATE TABLE IF NOT EXISTS cards ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 200), "column" TEXT NOT NULL CHECK ("column" IN ('todo', 'doing', 'done')), sort_order INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')) ); CREATE INDEX IF NOT EXISTS idx_cards_column_sort ON cards("column", sort_order); `); export const queries = { listByColumn: db.prepare<[Column], Card>( `SELECT * FROM cards WHERE "column" = ? ORDER BY sort_order, id` ), insert: db.prepare<[string, Column, number]>( `INSERT INTO cards (title, "column", sort_order) VALUES (?, ?, ?)` ), getById: db.prepare<[number], Card>(`SELECT * FROM cards WHERE id = ?`), move: db.prepare<[Column, number]>( `UPDATE cards SET "column" = ? WHERE id = ?` ), remove: db.prepare<[number]>(`DELETE FROM cards WHERE id = ?`), maxSort: db.prepare<[Column], { m: number | null }>( `SELECT COALESCE(MAX(sort_order), -1) AS m FROM cards WHERE "column" = ?` ), }; export default db; ``` Three things worth noting. First, `column` is a reserved word in SQL, so we quote it consistently — both in the schema and every prepared statement. Second, the `CHECK` constraint on `"column"` lets the database itself reject bad enum values; the TypeScript type narrows the same set in code, but SQL is the final guard. Third, `better-sqlite3` is **synchronous by design**[^3] — there is no `await` here, and a single Node event loop tick can run a full transaction without contention. That property is what makes htmx-style fragment rendering so cheap. ## Step 3 — The Express 5 skeleton with HTML escaping Create `src/server.ts`: ```ts import express from "express"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { queries } from "./db.js"; import { renderBoard, renderCard, renderError } from "./views.js"; import { sse } from "./sse.js"; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const app = express(); app.use(express.urlencoded({ extended: false })); app.use(express.static(path.join(__dirname, "..", "public"))); app.get("/", (_req, res) => { const board = { todo: queries.listByColumn.all("todo"), doing: queries.listByColumn.all("doing"), done: queries.listByColumn.all("done"), }; res.type("html").send(renderBoard(board)); }); const port = Number(process.env.PORT ?? 3000); app.listen(port, () => { console.log(`htmx-kanban listening on http://localhost:${port}`); }); ``` Express 5 handles thrown errors and rejected promises in async handlers natively, so we no longer need the `express-async-errors` shim that v4 required.[^4] The `express.urlencoded` middleware is what lets htmx's default `application/x-www-form-urlencoded` POST body deserialize into `req.body`. Now create `src/views.ts` for the HTML renderers. We do not pull in a templating engine — for a hypermedia app, raw template literals plus a tiny `escape()` helper is all you need: ```ts import type { Card, Column } from "./db.js"; const ESCAPE_MAP: Record = { "&": "&", "<": "<", ">": ">", '"': """, "'": "'", }; export const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ESCAPE_MAP[c] ?? c); export const renderCard = (card: Card): string => `

${esc(card.title)}

`; const renderColumn = (col: Column, cards: Card[]) => `

${col}

${cards.length}

${cards.map(renderCard).join("")}

`; export const renderBoard = (board: Record) => ` htmx kanban

${(["todo", "doing", "done"] as Column[]).map((c) => renderColumn(c, board[c])).join("")}

`; export const renderError = (msg: string) => `

${esc(msg)}

`; ``` A few htmx-specific decisions to call out: - **`hx-confirm`** on the delete button shows the browser's native confirm dialog before the request fires.[^5] - **`hx-swap="outerHTML swap:200ms"`** delays the DOM swap by 200 ms, which gives a CSS transition time to animate the card out before it disappears. - The body element carries `hx-ext="sse,response-targets" sse-connect="/events"` — htmx wires up an `EventSource` to that URL and listens for named events.[^6] The `#toast` div has `sse-swap="toast"`, meaning *only* events named `toast` trigger a swap there. We will use other event names for live card updates. (The `response-targets` extension is along for the ride and is what enables the `hx-target-4xx` attribute we use later in Step 6.) Add `public/style.css` to make the board look like a kanban (any minimal CSS works — keep it short): ```css * { box-sizing: border-box; } body { font: 16px/1.4 system-ui; margin: 0; padding: 1rem; background: #0f172a; color: #e2e8f0; } .board { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; } .col { background: #1e293b; border-radius: 8px; padding: 1rem; } .col header { display: flex; justify-content: space-between; align-items: baseline; } .cards { list-style: none; padding: 0; margin: 0 0 1rem; } .card { background: #334155; border-radius: 6px; padding: 0.5rem; margin-bottom: 0.5rem; display: flex; gap: 0.5rem; align-items: center; transition: opacity 200ms; } .card.htmx-swapping { opacity: 0; } .card span { flex: 1; } button { background: #475569; color: inherit; border: 0; padding: 0.25rem 0.5rem; border-radius: 4px; cursor: pointer; } button:hover { background: #64748b; } input[name="title"] { padding: 0.5rem; border-radius: 4px; border: 0; width: 100%; margin-bottom: 0.5rem; } .error { color: #fca5a5; margin: 0.5rem 0; } #toast:not(:empty) { position: fixed; bottom: 1rem; right: 1rem; background: #1e3a8a; padding: 0.75rem 1rem; border-radius: 6px; } ``` That `.htmx-swapping` rule is the matching half of the `swap:200ms` setting — htmx adds the class while the swap is in flight, your CSS animates opacity, and the browser does the rest. ## Step 4 — Wire up Create, Move, Delete with HTML fragments Now add the mutation routes. Each one returns an HTML fragment, never JSON. ```ts // src/server.ts (continued) app.post("/cards", (req, res) => { const title = String(req.body.title ?? "").trim(); const column = String(req.body.column ?? "") as "todo" | "doing" | "done"; if (!title || title.length > 200) { return res.status(400).type("html").send(renderError("Title is required (1–200 chars).")); } if (!["todo", "doing", "done"].includes(column)) { return res.status(400).type("html").send(renderError("Invalid column.")); } const nextSort = (queries.maxSort.get(column)?.m ?? -1) + 1; const result = queries.insert.run(title, column, nextSort); const card = queries.getById.get(Number(result.lastInsertRowid)); if (!card) return res.status(500).type("html").send(renderError("Insert failed.")); sse.broadcast("card-added", renderCard(card) + countOob(column)); res.type("html").send(renderCard(card)); }); app.put("/cards/:id/move", (req, res) => { const id = Number(req.params.id); const column = String(req.body.column ?? "") as "todo" | "doing" | "done"; const existing = queries.getById.get(id); if (!existing) return res.status(404).type("html").send(renderError("Card not found.")); if (!["todo", "doing", "done"].includes(column)) { return res.status(400).type("html").send(renderError("Invalid column.")); } queries.move.run(column, id); const updated = queries.getById.get(id); if (!updated) return res.status(500).type("html").send(renderError("Move failed.")); // The mover's own response moves the card by replacing it with a fragment that // re-attaches it under the new column via hx-swap-oob. const fragment = oobInsert(updated) + countOob(existing.column) + countOob(column); sse.broadcast("card-moved", fragment); res.type("html").send(`

${fragment}`); }); app.delete("/cards/:id", (req, res) => { const id = Number(req.params.id); const card = queries.getById.get(id); if (!card) return res.status(404).send(""); queries.remove.run(id); sse.broadcast("card-removed", `

${countOob(card.column)}`); res.type("html").send(""); }); function oobInsert(card: Card): string { // Returns a card fragment plus an OOB instruction to append it to the right column's

${renderCard(card)}

${count}

` — finds the existing element on the page with id `card-42` and applies the `delete` swap strategy. No selector needed: by default an element with `hx-swap-oob` is matched against the live DOM by `id`. - `

#hypermedia

شرح htmx: TypeScript Express Live