TradJS: a Bun web framework that uses the browser instead of fighting it · Gor Berlian · diadem.fun
← Gor Berlian
ArticleNov 18, 20263 min read

TradJS: a Bun web framework that uses the browser instead of fighting it

Contents

Repository: https://github.com/7flash/TradJS · Package: bun add tradjs (npm tradjs, version 4.6.5) · License: MIT

TradJS renders pages on the server and lets the browser do what it already does well: real links, real form posts, real back and forward buttons. Most pages run no JavaScript at all. A page that needs interaction gets a small script next to it that mounts exactly where it is needed.

What you get#

  • File-based routes. app/page.tsx is / and app/notes/page.tsx is /notes. app/api/notes/route.ts answers GET/POST at /api/notes, and [id] folders take parameters.
  • Layouts and middleware. A layout.tsx wraps every page below it. middleware.ts runs before them and passes typed values (locals, such as the signed-in user) to pages.
  • Browser scripts only where needed. Put page.client.tsx next to a page and its default export mounts in the browser. It can return a cleanup function, which runs when the browser puts the page into its back/forward cache.
  • Smooth navigation without a client router. Cross-document view transitions make ordinary page loads feel instant.
  • Security by default:
    • forms and fetches from other sites are refused (CSRF);
    • javascript: links, srcdoc and unsafe style URLs are dropped on the server and in the browser;
    • error details are hidden in production.
  • Static pages with export const ssg = true, including routes with parameters.
  • A starter app (tradjs init --template app): accounts and sessions, notes with edit/delete, pages of 20, live updates across tabs, a JSON API and accessible forms. It is in review for the next release.
// app/page.tsx
export default function Home() {
  return <main><h1>Hello</h1><div id="counter" /></main>;
}

// app/page.client.tsx
import { render } from "tradjs/client";
export default function mount() {
  let n = 0;
  const root = document.getElementById("counter")!;
  const draw = () => render(<button onClick={() => { n++; draw(); }}>Clicked {n}</button>, root);
  draw();
}

Proof it works#

Unit tests (1,673 of them) were not enough, so the starter app is also checked in a real browser:

  • a script scaffolds it, installs it from npm and starts the server;
  • it then drives headless Chrome through 30 user steps, including a second tab, a second user, hostile input, forged cross-site posts and keyboard-only use;
  • each step saves a screenshot.

Starter app home page

A wrong password brings the form back with a message

That browser check found bugs the unit tests had missed:

  • Text responses were downloaded. A route returning plain text reached the browser as a download. Fixed in 4.6.4.
  • Browser-drawn SVG icons were blank. <use xlinkHref> drawn in the browser pointed nowhere. Fixed in 4.6.5; the server and browser now produce identical SVG.
  • tradjs start failed from another folder. Started outside the app's own folder, every page returned an error. Fixed for the next release.

Two more test matrices feed the same releases:

  • Server vs browser: the same random pages rendered both ways must give the same document.
  • Hostile requests: 599 attacks, including path traversal, forged origins, cache poisoning and header abuse.
  • Source and README: https://github.com/7flash/TradJS
  • Changelog: https://github.com/7flash/TradJS/blob/master/CHANGELOG.md
  • Report on the real-browser checks: https://diadem.fun/coin/berlian/webstack-real-run-report
Gor Berlian

One person, many companies, one coin. Every project I build sends a share of its revenue back to buy $BERLIAN on the open market, and every buy is published with its transaction.

See the page

More from Gor Berlian