melina
v2.5.4
Published
A lightweight web framework for Bun with Next.js-style routing and zero-config builds.
Maintainers
mementsReadme
Melina.js 🦊
Bun-native web framework — server-rendered JSX + lightweight client runtime
Melina.js is a web framework built for Bun. Pages are server-rendered JSX — write components that run on the server, render to HTML, and arrive at the browser instantly. Client interactivity is added via mount scripts — small .client.tsx files that hydrate specific parts of the page with a zero-dependency ~2KB VDOM runtime.
No React on the client. No hydration mismatch. No bundle bloat.
Server (Bun) Browser
┌──────────────┐ ┌──────────────┐
│ page.tsx │──HTML──▶ │ Static DOM │
│ layout.tsx │ │ │
│ api/route.ts│ │ .client.tsx │
│ middleware │ │ mount() │
│ SSG cache │ │ VDOM render │
└──────────────┘ └──────────────┘Features
- File-based routing — Next.js App Router convention (
app/page.tsx→/) - Nested layouts —
layout.tsxat any level, composed automatically - Mount scripts —
page.client.tsxadds interactivity without shipping React - API routes —
app/api/*/route.tswithGET,POST, etc. - Dynamic routes —
app/post/[id]/page.tsx→/post/:id - SSG —
export const ssg = trueto pre-render at startup, serve from memory <Head>component — Declarative<title>,<meta>per page during SSR- Error boundaries —
error.tsxcatches render errors with layout chrome - Middleware —
middleware.tsat any route level, runs root→leaf - Scoped CSS —
page.cssorstyle.cssscoped to route segments - Tailwind CSS v4 — Built-in PostCSS +
@tailwindcss/postcsssupport - Streaming — Return
AsyncGeneratorfrom API routes for SSE - In-memory builds — No
dist/folder — assets built and served from RAM - Import maps — Browser-native module resolution for client dependencies
- Pluggable reconcilers — Keyed, sequential, or replace strategies for VDOM diffing
- Hot reload — Dev-only SSE-based live reload. Watches client script dep trees, reloads browser on save (v2.5.0)
- Auto server-only stubbing — Scans
node_modulesforbun:*imports and auto-stubs them for browser builds - Build error reporting — Surfaces Bun build errors/warnings with file:line:column positions
- Observability — All operations instrumented with measure-fn
Quick Start
# Create a new project
npx melina init my-app
cd my-app
bun install
bun run server.tsOr from scratch:
// server.ts
import { start } from 'melina';
await start({
appDir: './app',
port: 3000,
defaultTitle: 'My App',
// hotReload: true, // opt-in in dev
});Project Structure
my-app/
├── app/
│ ├── layout.tsx # Root layout (wraps all pages)
│ ├── layout.client.tsx # Persistent client JS (survives navigation)
│ ├── globals.css # Global styles (Tailwind or plain CSS)
│ ├── page.tsx # Home page (/)
│ ├── page.client.tsx # Home page mount script
│ ├── page.css # Scoped CSS for home page
│ ├── middleware.ts # Root middleware (runs on every request)
│ ├── error.tsx # Error boundary
│ ├── about/
│ │ └── page.tsx # /about
│ ├── post/[id]/
│ │ └── page.tsx # /post/:id (dynamic route)
│ └── api/
│ └── messages/
│ └── route.ts # API: /api/messages
├── server.ts
└── package.jsonArchitecture
Server Pages
Pages export a default function that returns JSX. These run only on the server — you can access databases, read files, call APIs directly:
// app/page.tsx
export default function HomePage() {
const posts = db.query('SELECT * FROM posts LIMIT 10');
return (
<main>
<h1>Latest Posts</h1>
{posts.map(post => (
<article key={post.id}>
<h2>{post.title}</h2>
<p>{post.excerpt}</p>
</article>
))}
</main>
);
}Mount Scripts (Client Interactivity)
A page.client.tsx file adds interactivity to server-rendered HTML. Export a default mount() function — it receives the DOM after SSR:
// app/counter/page.client.tsx
import { render } from 'melina/client';
function Counter({ count, onIncrement }: { count: number; onIncrement: () => void }) {
return (
<div>
<span>{count}</span>
<button onClick={onIncrement}>+1</button>
</div>
);
}
export default function mount() {
const root = document.getElementById('counter-root');
if (!root) return;
let count = 0;
const update = () => {
render(<Counter count={count} onIncrement={() => { count++; update(); }} />, root);
};
update();
}Key design decisions:
- No hooks — Logic is explicit, not hidden behind magic closures
- No framework lock-in —
render(vnode, container)is the entire API - Works with XState — Mount scripts are the perfect place for state machines
Layouts
Layouts wrap pages and compose automatically from root to leaf:
// app/layout.tsx
export default function RootLayout({ children }: { children: any }) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<title>My App</title>
</head>
<body>
<nav><a href="/">Home</a></nav>
<main>{children}</main>
</body>
</html>
);
}layout.client.tsx is a persistent mount script — it survives page navigations, ideal for global UI like nav highlights or notification systems.
<Head> Component
Declarative per-page head management during SSR:
import { Head } from 'melina/web';
export default function AboutPage() {
return (
<>
<Head>
<title>About Us — My App</title>
<meta name="description" content="Learn about our team" />
<link rel="canonical" href="https://example.com/about" />
</Head>
<main><h1>About Us</h1></main>
</>
);
}API Routes
Export HTTP method handlers:
// app/api/messages/route.ts
export async function GET(req: Request) {
const messages = await db.getMessages();
return Response.json(messages);
}
export async function POST(req: Request) {
const body = await req.json();
await db.createMessage(body);
return Response.json({ ok: true });
}Streaming — Return an AsyncGenerator for Server-Sent Events:
export async function* GET(req: Request) {
for (let i = 0; i < 10; i++) {
yield `data: ${JSON.stringify({ count: i })}\n\n`;
await new Promise(r => setTimeout(r, 1000));
}
}SSG (Static Site Generation)
Opt in per page — pre-render at startup, serve from memory:
// Pre-render once, serve forever
export const ssg = true;
// Or with TTL (re-render after expiry)
export const ssg = { revalidate: 60 }; // seconds
export default function PricingPage() {
return <main><h1>Pricing</h1></main>;
}Middleware
middleware.ts files run before the page renders, root→leaf:
// app/middleware.ts
export default async function middleware(req: Request) {
const token = req.headers.get('authorization');
if (!token) {
return new Response('Unauthorized', { status: 401 });
}
// Return nothing to continue to the page
}Error Boundaries
error.tsx catches render errors and displays them with full layout chrome:
// app/error.tsx
export default function ErrorPage({ error }: { error: { message: string } }) {
return (
<div>
<h1>Something went wrong</h1>
<p>{error.message}</p>
</div>
);
}Dynamic Routes
app/post/[id]/page.tsx → /post/:id
app/user/[userId]/page.tsx → /user/:userIdexport default function PostPage({ params }: { params: { id: string } }) {
return <h1>Post #{params.id}</h1>;
}Scoped CSS
Add page.css or style.css alongside any page — it's automatically injected only for that route:
/* app/dashboard/page.css */
.metric-card {
background: linear-gradient(135deg, #1a1a2e, #16213e);
border-radius: 12px;
padding: 24px;
}Styling
Built-in Tailwind CSS v4 + PostCSS. Add globals.css in the app directory:
@import "tailwindcss";
@theme {
--color-primary: #0a0a0f;
--color-accent: #6366f1;
}Melina auto-discovers globals.css, global.css, or app.css.
API Reference
start(options)
High-level entry point:
import { start } from 'melina';
await start({
appDir: './app',
port: 3000,
defaultTitle: 'My App',
});serve(handler, options) + createAppRouter(options)
Lower-level API for custom setups:
import { serve, createAppRouter } from 'melina';
const handler = createAppRouter({
appDir: './app',
defaultTitle: 'My App',
globalCss: './app/globals.css',
hotReload: true,
});
serve(handler, { port: 3000, hotReload: true });Client: render(vnode, container)
The entire client API:
import { render, createElement } from 'melina/client';
render(<MyComponent />, document.getElementById('root'));CLI
npx melina init <project-name> # Create new project from template
npx melina start # Start dev serverShowcase
Run the built-in showcase to see every feature in action:
git clone https://github.com/7flash/melina.js.git
cd melina.js
bun install
bun run examples/showcase/server.ts
# → http://localhost:3000The showcase includes:
- SSR demo with live timestamps
- Counter with VDOM rendering
- XState state machine integration
- Reconciler strategy comparison and benchmarks
- SSG benchmark (SSR vs Cached SSR vs SSG response times)
- Error boundaries, middleware, scoped CSS,
<Head>component - Streaming API with animated progress
- Server throughput stress test
For Contributors
Design Philosophy
Melina is intentionally small. We don't add features unless they solve a real problem that the existing primitives can't handle. Two features we've explicitly decided against:
Why no Cached SSR
The comparison table on the SSG page shows three strategies: SSR, Cached SSR, and SSG. Cached SSR does not exist as a framework feature — and we don't plan to add it.
The pitch for Cached SSR is: "Render on the first request, cache the HTML, serve the cache for subsequent requests until TTL expires." But SSG with revalidation already does this — better:
// This is all you need. No Cached SSR required.
export const ssg = { revalidate: 60 }; // re-render every 60 seconds
export default function PricingPage() {
const prices = db.getPrices(); // fresh data on each revalidation
return <main><PriceTable prices={prices} /></main>;
}Here's the concrete comparison:
| | Cached SSR | SSG with revalidate |
|---|---|---|
| When cached | After first visitor requests | At startup (before any visitor) |
| First visitor | Pays full render cost | Instant response |
| Storage | JS string in memory (GC pressure) | ArrayBuffer (zero-copy, no GC) |
| Cache refresh | Next request after TTL expires triggers re-render | Background revalidation on timer |
| Invalidation | TTL only | TTL via revalidate, or manual via clearSSGCache() |
| Cold start | Slow (uncached) | Fast (pre-rendered) |
The critical difference: Cached SSR penalizes the first visitor with a full server render. SSG pre-renders at startup, so every visitor — including the first — gets an instant response. The revalidate option handles staleness automatically, and clearSSGCache() handles on-demand invalidation (e.g., after a webhook from your CMS).
If you need truly dynamic, per-request data (user-specific content, authenticated pages), use SSR. If you want caching, use SSG with revalidate. There's no use case where "SSR + cache the response" beats "SSG + periodic revalidation" — SSG is strictly better because it eliminates the cold-start penalty entirely.
Hot Reload (v2.5.0)
In dev mode, Melina watches your client script dependency trees and auto-reloads the browser on save:
hot-reload.tsusesfs.watch()on directories containing client scripts and their imports- When a file changes, an SSE event is sent to the browser via
/__melina_hmr - A reconnecting
EventSourceclient in the page triggerswindow.location.reload() - 150ms debounce handles editors that write multiple times per save
- Dep trees are walked using
Bun.Transpiler.scanImports()— only local imports are followed - Completely no-op in production
Apps can also configure server-only packages via package.json:
{
"melina": {
"serverOnly": ["my-db-adapter", "internal-auth-lib"]
}
}These packages will be stubbed with a Proxy in browser builds, preventing bun:* import errors.
Project Structure
src/
├── server/
│ ├── app-router.ts # Route matching, SSR pipeline, error boundaries
│ ├── build.ts # Asset build pipeline (JS, CSS, static files)
│ ├── serve.ts # HTTP server with measure-fn observability
│ ├── router.ts # File-based route discovery
│ ├── ssg.ts # Static site generation (pre-render + memory serve)
│ ├── ssr.ts # renderToString (VNode → HTML)
│ ├── head.ts # <Head> component (side-channel collection)
│ ├── imports.ts # Import map generation
│ ├── hot-reload.ts # Dev-only SSE hot reload + file watcher
│ └── types.ts # Shared types
├── client/
│ ├── render.ts # VDOM renderer + Fiber reconciler (~2KB)
│ ├── reconcilers/ # Pluggable diffing strategies
│ │ ├── keyed.ts # O(n log n) key-based with LIS
│ │ ├── sequential.ts # O(n) index-based
│ │ └── replace.ts # Full replace (baseline)
│ ├── jsx-runtime.ts # JSX transform for client bundles
│ ├── jsx-dom.ts # JSX-to-real-DOM for mount scripts
│ └── types.ts # VNode, Component, Props types
└── web.ts # Main entry pointObservability
Every operation is instrumented with measure-fn:
[a] ✓ Discover routes 8.10ms → 17 routes
[b] ... GET http://localhost:3000/
[b-a] ... Middleware: app
[b-a] ✓ Middleware: app 0.12ms
[b-b] ... Import page
[b-b] ✓ Import page 0.04ms
[b-c] ... SSR renderToString
[b-c] ✓ SSR renderToString 0.31ms
[build:d] ... Style: globals.css
[build:d] ✓ Style: globals.css 0.10ms
[b] ✓ GET http://localhost:3000/ 2.14msRunning Tests
bun testLicense
MIT © 7flash Import page 0.04ms [b-c] ... SSR renderToString [b-c] ✓ SSR renderToString 0.31ms [build:d] ... Style: globals.css [build:d] ✓ Style: globals.css 0.10ms [b] ✓ GET http://localhost:3000/ 2.14ms
### Running Tests
```bash
bun testLicense
MIT © 7flash