/* global React, ReactDOM, useTweaks, TweaksPanel, TweakSection, TweakRadio */
const { useState, useEffect, useRef, useCallback } = React;
/* ────────────────────────────────────────────────────────────
Hero / install
──────────────────────────────────────────────────────────── */
function InstallBar() {
const [copied, setCopied] = useState(false);
const cmd = "npx create-binsby@latest";
const onCopy = () => {
try { navigator.clipboard.writeText(cmd); } catch (e) {}
setCopied(true);
setTimeout(() => setCopied(false), 1400);
};
return (
$ {cmd}
{copied ? "✓ copied" : "copy"}
);
}
function Hero() {
return (
Ship real HTML.on purpose.
Binsby is a server-first React framework built around one constraint:
the server ships real HTML; the browser only runs what you explicitly allow.
);
}
/* ────────────────────────────────────────────────────────────
Why / principles
──────────────────────────────────────────────────────────── */
const PRINCIPLES = [
{ k: "01 / SSR by default", t: "Output is ordinary HTML",
p: "No edge magic, no virtual streaming protocol. The server renders, the browser receives HTML — same as it ever was." },
{ k: "02 / Islands, not oceans", t: "Hydration is opt-in",
p: "Mark a component as an island and it ships JS. Don’t, and it doesn’t. There is no global hydrate; there’s no blanket tax." },
{ k: "03 / The registry", t: "An allowlist for the browser",
p: "Every island lands in a registry you maintain. Auditing what can execute client-side is one file, not a vibe check." },
{ k: "04 / Don’t fight the tools", t: "Vite stays Vite, React stays React",
p: "No bespoke compiler tricks. No file conventions you can’t grep for. If you know React + Vite, you already know Binsby." },
];
function Why() {
return (
01 / WHY
Less framework, more web.
Built because meta-framework convenience kept turning into cleverness — hidden conventions,
implicit data flow, global hydration by default. Stuff that makes simple work feel like archaeology
once the app grows.
{PRINCIPLES.map((x) => (
))}
);
}
/* ────────────────────────────────────────────────────────────
Feature grid
──────────────────────────────────────────────────────────── */
const FEATURES = [
{ i: "", t: "Real HTML", p: "Routes return strings. View source actually shows your page." },
{ i: "◇", t: "Islands", p: "Opt-in interactivity per component. The default is zero JS." },
{ i: "✓", t: "Registry", p: "One file lists everything that may run in the browser." },
{ i: "⌁", t: "Streaming", p: "Server renders progressively. The shell arrives in milliseconds." },
{ i: "⚡", t: "Vite-native", p: "HMR, plugins, build pipeline — your existing Vite config still works." },
{ i: "△", t: "Edge-friendly", p: "Deploy to Node, Bun, Deno, Workers. The runtime is small on purpose." },
{ i: "≡", t: "Forms first", p: "Progressive enhancement is the default. Forms work without JS, then upgrade." },
{ i: "↺", t: "Resumable nav", p: "Client router takes over after first paint, only when an island says so." },
{ i: "⌘", t: "TypeScript native", p: "End-to-end types from loaders to islands. No codegen step." },
];
function Features() {
return (
02 / FEATURES
The whole framework, on one page.
{FEATURES.map((f) => (
))}
);
}
/* ────────────────────────────────────────────────────────────
Tabbed code example
──────────────────────────────────────────────────────────── */
const TABS = [
{
id: "page",
name: "app/routes/index.tsx",
badge: null,
code: (
<>
1 // Server component. No "use client". No hydration. {"\n"}
2 import Counter from "./Counter.island" {"\n"}
3 import {"{"} getStats {"}"} from "~/lib/stats" {"\n"}
4 {"\n"}
5 export default async function Page () {"{"}
{"\n"}6 const stats = await getStats();{"\n"}
7 return ({"\n"}
8 <main >{"\n"}
9 <h1 >Hello, server.</h1 >{"\n"}
10 <p >{"{stats.requests} reqs/s · 0 KB JS shipped"}</p >{"\n"}
11 <Counter initial={"{0}"} /> {"// ← only this hydrates"} {"\n"}
12 </main >{"\n"}
13 );{"\n"}
14 {"}"}
)
},
{
id: "island",
name: "app/routes/Counter.island.tsx",
badge: "island",
code: (
<>
1 // .island.tsx suffix = ships to the browser. {"\n"}
2 import {"{"} useState {"}"} from "react" {"\n"}
3 {"\n"}
4 export default function Counter ({"{"} initial {"}"}: {"{"} initial: number {"}"}) {"{"}
{"\n"}5 const [n, setN] = useState(initial);{"\n"}
6 return ({"\n"}
7 <button onClick={"{() => setN(n + 1)}"}>{"\n"}
8 Clicked {"{n}"} times{"\n"}
9 </button >{"\n"}
10 );{"\n"}
11 {"}"}
)
},
{
id: "registry",
name: "binsby.config.ts",
badge: null,
code: (
<>
1 // The allowlist. If it's not here, it can't hydrate. {"\n"}
2 import {"{"} defineRegistry {"}"} from "binsby" {"\n"}
3 {"\n"}
4 export default defineRegistry({"{"}
{"\n"}5 islands: {"{"}
{"\n"}6 Counter: () => import ("~/routes/Counter.island" ),{"\n"}
7 ThemeToggle: () => import ("~/components/ThemeToggle.island" ),{"\n"}
8 {"},"}{"\n"}
9 ssr: {"{"} streaming: true {"},"}{"\n"}
10 {"});"}
)
},
];
function CodeTabs() {
const [active, setActive] = useState("page");
const cur = TABS.find(t => t.id === active);
const isIsland = active === "island";
return (
03 / CODE
Three files. That’s the whole shape.
{TABS.map(t => (
setActive(t.id)}
>
↯ {t.badge} }
))}
{isIsland
? <>● ships to browser
: <>● server-only · 0 KB}
{cur.code}
// No "use client" directives. No
invisible boundaries. The .island.tsx suffix and the registry are the contract.
);
}
/* ────────────────────────────────────────────────────────────
Architecture diagram (3-step animation)
──────────────────────────────────────────────────────────── */
function Diagram() {
const [step, setStep] = useState(0);
const [playing, setPlaying] = useState(true);
const timer = useRef(null);
useEffect(() => {
if (!playing) return;
timer.current = setInterval(() => setStep(s => (s + 1) % 3), 2200);
return () => clearInterval(timer.current);
}, [playing]);
const stepNames = ["server renders", "html arrives", "island hydrates"];
return (
04 / ARCHITECTURE
Server → HTML → island.
{/* arrows */}
= 1 ? "lit" : "")} style={{ left: "calc(33.33% + 0px)", marginLeft: -10 }}>
= 2 ? "cyan" : "")} style={{ left: "calc(66.66% + 0px)", marginLeft: -10 }}>
{/* node 1: server */}
◇ server · routes/index.tsx
{"// async, has db access"}
<Page>
<h1> Hello.</h1>
<Counter initial={"{0}"} />
</Page>
// renderToString()
{/* node 2: html on the wire */}
→ html on the wire
<!doctype html>
<main>
<h1> Hello.</h1>
↯ island id="Counter"
<button> Clicked 0 times</button>
↯ /island
</main>
{"// 0.4 KB · gzip"}
{/* node 3: island hydrates */}
↯ browser · registry lookup
// registry["Counter"]
import ("./Counter.island" )
.then(hydrate )
↯ Counter · hydrated
// page total: 4.2 KB
// other components: never load
setPlaying(p => !p)}>
{playing ? "❚❚ pause" : "▶ play"}
step {step + 1} / 3 · {stepNames[step]}
{[0,1,2].map(i => (
{ setStep(i); setPlaying(false); }}
>
))}
);
}
/* ────────────────────────────────────────────────────────────
Live island demo
──────────────────────────────────────────────────────────── */
function IslandDemo() {
const [count, setCount] = useState(0);
const [bytes, setBytes] = useState(0);
const [hydratedAt, setHydratedAt] = useState(null);
useEffect(() => {
// simulate hydration cost on mount, once
const t = setTimeout(() => {
setBytes(412);
setHydratedAt(Date.now());
}, 220);
return () => clearTimeout(t);
}, []);
return (
05 / LIVE
One island. Everything else is HTML.
preview · view-source view
app/routes/index.tsx
<main>
<h1>Hello, server.</h1>
<p>Real HTML. No JS yet.</p>
↯ island · Counter · hydrated {hydratedAt ? "•" : "…"}
setCount(c => Math.max(0, c - 1))} aria-label="decrement">−
{count}
setCount(c => c + 1)} aria-label="increment">+
setCount(0)}>reset
<footer>Still HTML.</footer>
</main>
JS shipped to browser
{bytes ? bytes + " B" : "…"}
Components hydrated
1 / 47
SSR time
14 ms
Counter clicks (state)
{count}
binsby.config.ts · registry
Counter ↯ hydrated
ThemeToggle — idle
Search — idle
// click +/−. notice no other component on this page
);
}
/* ────────────────────────────────────────────────────────────
Comparison
──────────────────────────────────────────────────────────── */
const ROWS = [
{ l: "Hydration model", s: "How JS reaches the browser",
binsby: ["yes", "Islands · opt-in"], next: ["opt", "RSC + 'use client'"], remix: ["no", "Full hydration"] },
{ l: "Default JS per route", s: "Empty page baseline",
binsby: ["yes", "0 KB"], next: ["opt", "~80 KB"], remix: ["no", "~70 KB"] },
{ l: "Client allowlist", s: "Auditable registry of what may run",
binsby: ["yes", "binsby.config.ts"], next: ["no", "Implicit"], remix: ["no", "Implicit"] },
{ l: "File conventions", s: "How routes are discovered",
binsby: ["yes", "Explicit imports"], next: ["opt", "Folder magic"], remix: ["opt", "Folder magic"] },
{ l: "Build tool", s: "What ships you the bundle",
binsby: ["yes", "Vite"], next: ["no", "Turbopack/webpack"], remix: ["yes", "Vite"] },
{ l: "RSC", s: "React Server Components",
binsby: ["no", "Not used"], next: ["yes", "Required"], remix: ["no", "Not used"] },
{ l: "Forms without JS", s: "Progressive enhancement",
binsby: ["yes", "Default"], next: ["opt", "With effort"], remix: ["yes", "Default"] },
{ l: "Lines in core runtime", s: "Approximate, audit-time",
binsby: ["yes", "~2k"], next: ["no", "huge"], remix: ["opt", "medium"] },
];
function Comparison() {
const cell = (v) => {
const [k, txt] = v;
const sym = k === "yes" ? "●" : k === "opt" ? "◐" : "○";
return {sym}{txt} ;
};
return (
06 / COMPARISON
How it differs.
Binsby
Next.js
Remix
{ROWS.map(r => (
{r.l}{r.s}
{cell(r.binsby)}
{cell(r.next)}
{cell(r.remix)}
))}
// ● yes · ◐ partial / opt-in · ○ no — comparison written by Binsby; mileage may vary
);
}
/* ────────────────────────────────────────────────────────────
CTA + Footer
──────────────────────────────────────────────────────────── */
function CTA() {
return (
◇ ship something small
Stop hydrating things you didn’t ask to.
Five-minute starter, no account, no telemetry. The whole runtime fits in a long-ish file.
);
}
function Footer() {
return (
);
}
/* ────────────────────────────────────────────────────────────
App + Tweaks
──────────────────────────────────────────────────────────── */
function App() {
const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
"background": "grid"
}/*EDITMODE-END*/;
const [tweaks, setTweak] = useTweaks(TWEAK_DEFAULTS);
useEffect(() => {
document.body.dataset.bg = tweaks.background;
}, [tweaks.background]);
return (
<>
setTweak("background", v)}
/>
);
}
ReactDOM.createRoot(document.getElementById("root")).render(