Benjamin Toby 7ef114ee70 Handle browser Errors.

2026-03-21 06:34:32 +01:00

29 KiB

Raw Blame History

Bunext

A server-rendering framework for React, built on Bun. Bunext handles file-system routing, SSR, HMR, and client hydration — using ESBuild to bundle client assets and Bun.serve as the HTTP server.

Philosophy

Bunext is focused on server-side rendering and processing. Every page is rendered on the server on every request. The framework deliberately does not implement client-side navigation, SPA routing, or client-side state management — those concerns belong in client-side libraries and are orthogonal to what Bunext is solving.

The goal is a framework that is:

Fast — Bun's runtime speed and ESBuild's bundling make the full dev loop snappy
Transparent — the entire request pipeline is readable and debugable
Standard — server functions and API handlers use native Web APIs (Request, Response, URL) with no custom wrappers

Requirements
Installation
Quick Start
CLI Commands
Project Structure
File-System Routing
- Non-Routed Directories
Pages
API Routes
- Route Config (Body Size Limit)
Error Pages
Static Files
Caching
Configuration
- Middleware
Environment Variables
How It Works

Requirements

Bun v1.0 or later
TypeScript 5.0+
React 19 and react-dom 19 (peer dependencies)

Installation

Install Bunext directly from GitHub:

bun add github:moduletrace/bunext

Install required peer dependencies:

bun add react react-dom
bun add -d typescript @types/react @types/react-dom

Quick Start

Create a minimal project layout:

my-app/
├── src/
│   └── pages/
│       └── index.tsx
├── bunext.config.ts      # optional
└── package.json

Create your first page (src/pages/index.tsx):

export default function HomePage() {
    return <h1>Hello from Bunext!</h1>;
}

Start the development server:

bunext dev

Open http://localhost:7000 in your browser.

CLI Commands

Command	Description
`bunext dev`	Start the development server with HMR and file watching.
`bunext build`	Bundle all pages for production. Outputs artifacts to `public/pages/`.
`bunext start`	Start the production server using pre-built artifacts.

# Development
bunext dev

# Production build
bunext build

# Production server (must run build first)
bunext start

Note: bunext start will exit with an error if public/pages/map.json does not exist. Always run bunext build before bunext start.

Project Structure

A typical Bunext project has the following layout:

my-app/
├── src/
│   └── pages/             # File-system routes (pages and API handlers)
│       ├── __root.tsx     # Optional: root layout wrapper for all pages
│       ├── index.tsx      # Route: /
│       ├── about.tsx      # Route: /about
│       ├── 404.tsx        # Optional: custom 404 page
│       ├── 500.tsx        # Optional: custom 500 page
│       ├── blog/
│       │   ├── index.tsx  # Route: /blog
│       │   └── [slug].tsx # Route: /blog/:slug (dynamic)
│       └── api/
│           └── users.ts   # API route: /api/users
├── public/                # Static files and bundler output
│   └── __bunext/
│       ├── pages/         # Generated by bundler (do not edit manually)
│       │   └── map.json   # Artifact map used by production server
│       └── cache/         # File-based HTML cache (production only)
├── bunext.config.ts       # Optional configuration
├── tsconfig.json
└── package.json

File-System Routing

Bunext uses Bun.FileSystemRouter with Next.js-style routing. Pages live in src/pages/ and are automatically mapped to URL routes:

File path	URL path
`src/pages/index.tsx`	`/`
`src/pages/about.tsx`	`/about`
`src/pages/blog/index.tsx`	`/blog`
`src/pages/blog/[slug].tsx`	`/blog/:slug`
`src/pages/users/[id]/index.tsx`	`/users/:id`
`src/pages/api/users.ts`	`/api/users`

Dynamic route parameters (e.g. [slug]) are available in the server function via ctx.req.url or from the query field in the server response.

Non-Routed Directories

Directories whose name contains -- or a parenthesis (( or )) are completely ignored by the router. Use this to co-locate helper components, utilities, or shared logic directly inside src/pages/ alongside the routes that use them, without them becoming routes.

Naming pattern	Effect
`(components)/`	Ignored — not routed
`--utils--/`	Ignored — not routed
`--lib/`	Ignored — not routed

src/pages/
├── blog/
│   ├── (components)/       # Not a route — co-location directory
│   │   ├── PostCard.tsx    # Used by index.tsx and [slug].tsx
│   │   └── PostList.tsx
│   ├── index.tsx           # Route: /blog
│   └── [slug].tsx          # Route: /blog/:slug
└── index.tsx               # Route: /

Pages

Basic Page

A page file must export a default React component. The component receives server-side props automatically.

// src/pages/index.tsx
export default function HomePage() {
    return <h1>Hello, World!</h1>;
}

Server Function

Export a server function to run server-side logic before rendering. The return value's props field is spread into the page component as props, and query carries route query parameters.

// src/pages/profile.tsx
import type { BunextPageServerFn } from "bunext/src/types";

type Props = {
    props?: { username: string; bio: string };
    query?: Record<string, string>;
    url?: URL;
};

export const server: BunextPageServerFn<{
    username: string;
    bio: string;
}> = async (ctx) => {
    // ctx.req — the raw Request object
    // ctx.url — the parsed URL
    // ctx.query — query string parameters
    // ctx.resTransform — optional response interceptor

    const username = "alice";
    const bio = "Software engineer";

    return {
        props: { username, bio },
    };
};

export default function ProfilePage({ props, url }: Props) {
    return (
        <div>
            <h1>{props?.username}</h1>
            <p>{props?.bio}</p>
            <p>Current path: {url?.pathname}</p>
        </div>
    );
}

The server function receives a ctx object (type BunxRouteParams) with:

Field	Type	Description
`req`	`Request`	Raw Bun/Web Request object
`url`	`URL`	Parsed URL
`body`	`any`	Parsed request body
`query`	`any`	Query string parameters
`resTransform`	`(res: Response) => Promise<Response>\|Response`	Intercept and transform the final response

Default Server Props

Every page component automatically receives a url prop — a copy of the request URL object — even if no server function is exported. This means you can always read URL data (pathname, search params, origin, etc.) directly from component props without writing a server function.

// src/pages/index.tsx
import type { BunextPageModuleServerReturnURLObject } from "bunext/src/types";

type Props = {
    url?: BunextPageModuleServerReturnURLObject;
};

export default function HomePage({ url }: Props) {
    return (
        <div>
            <p>Visiting: {url?.pathname}</p>
            <p>Origin: {url?.origin}</p>
        </div>
    );
}

The url prop exposes the following fields from the standard Web URL interface:

Field	Type	Example
`href`	`string`	`"https://example.com/blog?q=1"`
`origin`	`string`	`"https://example.com"`
`protocol`	`string`	`"https:"`
`host`	`string`	`"example.com"`
`hostname`	`string`	`"example.com"`
`port`	`string`	`""`
`pathname`	`string`	`"/blog"`
`search`	`string`	`"?q=1"`
`searchParams`	`URLSearchParams`	`URLSearchParams { q: "1" }`
`hash`	`string`	`""`
`username`	`string`	`""`
`password`	`string`	`""`

Redirects from Server

Return a redirect object from the server function to redirect the client:

export const server: BunextPageServerFn = async (ctx) => {
    const isLoggedIn = false; // check auth

    if (!isLoggedIn) {
        return {
            redirect: {
                destination: "/login",
                permanent: false, // uses 302
                // status_code: 307 // override status code
            },
        };
    }

    return { props: {} };
};

permanent: true sends a 301 redirect. Otherwise it sends 302, or the value of status_code if provided.

Custom Response Options

Control status codes, headers, and other response options from the server function:

export const server: BunextPageServerFn = async (ctx) => {
    return {
        props: { message: "Created" },
        responseOptions: {
            status: 201,
            headers: {
                "X-Custom-Header": "my-value",
            },
        },
    };
};

SEO Metadata

Export a meta object to inject SEO and Open Graph tags into the <head>:

import type { BunextPageModuleMeta } from "bunext/src/types";

export const meta: BunextPageModuleMeta = {
    title: "My Page Title",
    description: "A description for search engines.",
    keywords: ["bun", "react", "ssr"],
    author: "Alice",
    robots: "index, follow",
    canonical: "https://example.com/about",
    themeColor: "#ffffff",
    og: {
        title: "My Page Title",
        description: "Shared on social media.",
        image: "https://example.com/og-image.png",
        url: "https://example.com/about",
        type: "website",
        siteName: "My Site",
        locale: "en_US",
    },
    twitter: {
        card: "summary_large_image",
        title: "My Page Title",
        description: "Shared on Twitter.",
        image: "https://example.com/twitter-image.png",
        site: "@mysite",
        creator: "@alice",
    },
};

export default function AboutPage() {
    return <p>About us</p>;
}

Dynamic Metadata

meta can also be an async function that receives the request context and server response:

import type { BunextPageModuleMetaFn } from "bunext/src/types";

export const meta: BunextPageModuleMetaFn = async ({ ctx, serverRes }) => {
    return {
        title: `Post: ${serverRes?.props?.title ?? "Untitled"}`,
        description: serverRes?.props?.excerpt,
    };
};

Custom Head Content

Export a Head functional component to inject arbitrary HTML into <head>. It receives the server response and request context:

import type { BunextPageHeadFCProps } from "bunext/src/types";

export function Head({ serverRes, ctx }: BunextPageHeadFCProps) {
    return (
        <>
            <link rel="preconnect" href="https://fonts.googleapis.com" />
            <link rel="icon" href="/public/favicon.ico" />
        </>
    );
}

export default function Page() {
    return <main>Content</main>;
}

Root Layout

Create src/pages/__root.tsx to wrap every page in a shared layout. The root component receives children (the current page component) along with all server props:

// src/pages/__root.tsx
import type { PropsWithChildren } from "react";

export default function RootLayout({
    children,
    props,
}: PropsWithChildren<any>) {
    return (
        <>
            <header>My App</header>
            <main>{children}</main>
            <footer>© 2025</footer>
        </>
    );
}

API Routes

Create files under src/pages/api/ to define API endpoints. The default export receives a BunxRouteParams object and must return a standard Response.

// src/pages/api/hello.ts
import type { BunxRouteParams } from "bunext/src/types";

export default async function handler(ctx: BunxRouteParams): Promise<Response> {
    return Response.json({ message: "Hello from the API" });
}

API routes are matched at /api/<filename>. Because the handler returns a plain Response, you control the status code, headers, and body format entirely:

// src/pages/api/users.ts
import type { BunxRouteParams } from "bunext/src/types";

export default async function handler(ctx: BunxRouteParams): Promise<Response> {
    if (ctx.req.method !== "GET") {
        return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const users = [{ id: 1, name: "Alice" }];

    return Response.json({ success: true, data: users });
}

The ctx parameter has the same shape as the page server function context — see the Server Function section for the full field reference. The ctx.server field additionally exposes the Bun Server instance.

Route Config (Body Size Limit)

Export a config object to override the per-route request body limit (default: 10 MB):

import type {
    BunextServerRouteConfig,
    BunxRouteParams,
} from "bunext/src/types";

export const config: BunextServerRouteConfig = {
    maxRequestBodyMB: 50, // allow up to 50 MB
};

export default async function handler(ctx: BunxRouteParams): Promise<Response> {
    // handle large uploads
    return Response.json({ success: true });
}

Error Pages

Bunext serves built-in fallback error pages, but you can override them by creating pages in src/pages/:

File	Triggered when
`src/pages/404.tsx`	No matching route is found
`src/pages/500.tsx`	An unhandled error occurs during render

The error message is passed as children to the component:

// src/pages/404.tsx
import type { PropsWithChildren } from "react";

export default function NotFoundPage({ children }: PropsWithChildren) {
    return (
        <div>
            <h1>404 — Page Not Found</h1>
            <p>{children}</p>
        </div>
    );
}

If no custom error pages exist, Bunext uses built-in preset components.

Static Files

Place static files in the public/ directory. They are served at the /public/ URL path:

public/
├── logo.png         → http://localhost:7000/public/logo.png
├── styles.css       → http://localhost:7000/public/styles.css
└── favicon.ico      → http://localhost:7000/favicon.ico

Favicons are also served from /public/ but matched directly at /favicon.*.

Caching

Bunext includes a file-based HTML cache for production. Caching is disabled in development — every request renders fresh. In production, a cron job runs every 30 seconds to delete expired cache entries.

Cache files are stored in public/__bunext/cache/. Each cached page produces two files:

File	Contents
`<key>.res.html`	The cached HTML response body
`<key>.meta.json`	Metadata: creation timestamp, expiry, paradigm

The cache is cold on first request: the first visitor triggers a full server render and writes the cache. Every subsequent request within the expiry window receives the cached HTML directly, bypassing the server function, component render, and bundler lookup. A cache hit is indicated by the response header X-Bunext-Cache: HIT.

Enabling Cache Per Page

Export a config object from a page file to opt that page into caching:

// src/pages/products.tsx
import type { BunextRouteConfig } from "bunext/src/types";

export const config: BunextRouteConfig = {
    cachePage: true,
    cacheExpiry: 300, // seconds — optional, overrides the global default
};

export default function ProductsPage() {
    return <h1>Products</h1>;
}

Dynamic Cache Control from Server Function

Cache settings can also be returned from the server function, which lets you conditionally enable caching based on request data:

import type { BunextPageServerFn } from "bunext/src/types";

export const server: BunextPageServerFn = async (ctx) => {
    const data = await fetchProducts();

    return {
        props: { data },
        cachePage: true,
        cacheExpiry: 600, // 10 minutes
    };
};

export default function ProductsPage({ props }: any) {
    return <ul>{props.data.map((p: any) => <li key={p.id}>{p.name}</li>)}</ul>;
}

If both module.config.cachePage and serverRes.cachePage are set, module.config takes precedence.

Cache Expiry

Expiry resolution order (first truthy value wins):

cacheExpiry on the page config export or server return (per-page, in seconds)
defaultCacheExpiry in bunext.config.ts (global default, in seconds)
Built-in default: 3600 seconds (1 hour)

The cron job checks all cache entries every 30 seconds and deletes any whose age exceeds their expiry. Static bundled assets (JS/CSS in public/__bunext/) receive a separate HTTP Cache-Control: public, max-age=604800 header (7 days) via the browser cache — this is independent of the page HTML cache.

Cache Behavior and Limitations

Production only. Caching never activates in development (bunext dev).
Cold start required. The cache is populated on the first request; there is no pre-warming step.
Immutable within the expiry window. Once a page is cached, writeCache skips all subsequent write attempts for that key until the cron job deletes the expired entry. There is no manual invalidation API.
Cache is not cleared on rebuild. Deploying a new build does not automatically flush public/__bunext/cache/. Stale HTML files referencing old JS bundles can be served until they expire. Clear the cache directory as part of your deploy process if needed.
No key collision. Cache keys are generated via encodeURIComponent() on the URL path. /foo/bar encodes to %2Ffoo%2Fbar and /foo-bar to %2Ffoo-bar — distinct filenames with no collision risk.

Configuration

Create a bunext.config.ts file in your project root to configure Bunext:

// bunext.config.ts
import type { BunextConfig } from "bunext/src/types";

const config: BunextConfig = {
    port: 3000, // default: 7000
    origin: "https://example.com",
    distDir: ".bunext", // directory for internal build artifacts
    assetsPrefix: "_bunext/static",
    globalVars: {
        MY_API_URL: "https://api.example.com",
    },
    development: false, // forced by the CLI; set manually if needed
};

export default config;

Option	Type	Default	Description
`port`	`number`	`7000`	HTTP server port
`origin`	`string`	—	Canonical origin URL
`distDir`	`string`	`.bunext`	Internal artifact directory
`assetsPrefix`	`string`	`_bunext/static`	URL prefix for static assets
`globalVars`	`{ [k: string]: any }`	—	Variables injected globally at build time
`development`	`boolean`	—	Overridden to `true` by `bunext dev` automatically
`defaultCacheExpiry`	`number`	`3600`	Global page cache expiry in seconds
`middleware`	`(params: BunextConfigMiddlewareParams) => Response \| undefined \| Promise<...>`	—	Global middleware — see Middleware

Middleware

Middleware runs on every request before any routing. Define it in bunext.config.ts via the middleware field. The function receives { req, url, server } (type BunextConfigMiddlewareParams).

If it returns a Response, that response is sent to the client immediately and no further routing occurs.
If it returns undefined (or nothing), the request proceeds normally through the router.

// bunext.config.ts
import type {
    BunextConfig,
    BunextConfigMiddlewareParams,
} from "bunext/src/types";

const config: BunextConfig = {
    middleware: async ({ req, url, server }) => {
        // Example: protect all /dashboard/* routes
        if (url.pathname.startsWith("/dashboard")) {
            const token = req.headers.get("authorization");

            if (!token) {
                return Response.redirect("/login", 302);
            }
        }

        // Return undefined to continue to the normal request pipeline
        return undefined;
    },
};

export default config;

The middleware can return any valid Response, including redirects, JSON, or HTML:

middleware: async ({ req, url }) => {
    // Block a specific path
    if (url.pathname === "/maintenance") {
        return new Response("Down for maintenance", { status: 503 });
    }

    // For API routes, return undefined to continue — the handler controls its own Response directly
},

Environment Variables

Variable	Description
`PORT`	Override the server port (takes precedence over config)

How It Works

Development Server

Running bunext dev:

Loads bunext.config.ts and sets development: true.
Initializes directories (.bunext/, public/pages/).
Creates a Bun.FileSystemRouter pointed at src/pages/.
Starts the ESBuild bundler in watch mode — it will automatically rebuild when file content changes.
Starts a file-system watcher on src/ — when a file is created or deleted (a "rename" event), it triggers a full bundler rebuild to update the entry points.
Waits for the first successful bundle.
Starts Bun.serve().

Production Build

Running bunext build:

Sets NODE_ENV=production.
Runs ESBuild once (not in watch mode) with minification enabled.
Writes all bundled artifacts to public/pages/ and the artifact map to public/pages/map.json.
Exits.

Production Server

Running bunext start:

Reads public/pages/map.json to load the pre-built artifact map.
Starts Bun.serve() without any bundler or file watcher.

Bundler

The bundler (allPagesBundler) uses ESBuild with three custom plugins:

tailwindcss plugin — Processes any .css files through PostCSS + Tailwind CSS before bundling.
virtual-entrypoints plugin — Generates an in-memory client hydration entry point for each page. Each entry imports the page component and calls hydrateRoot() against the server-rendered DOM node. If src/pages/__root.tsx exists, the page is wrapped in the root layout.
artifact-tracker plugin — After each build, collects all output file paths, content hashes, and source entrypoints into a BundlerCTXMap[]. This map is stored in global.BUNDLER_CTX_MAP and written to public/pages/map.json.

Output files are named [dir]/[name]/[hash] so filenames change when content changes, enabling cache-busting.

Hot Module Replacement

In development, Bunext injects a script into every HTML page that opens a Server-Sent Events (SSE) connection to /__hmr. When a rebuild completes and the bundle hash for a page changes, the server pushes an update event through the stream containing the new artifact metadata. The client then performs a true in-place HMR update — no full page reload:

If the page has a CSS bundle, the old <link rel="stylesheet"> is replaced with a new one pointing to the updated CSS file (cache-busted with ?t=<timestamp>).
The existing client hydration <script> (identified by id="bunext-client-hydration-script") is removed from the DOM.
A new <script type="module"> is injected pointing to the freshly rebuilt JS bundle (also cache-busted).
The new bundle calls window.__BUNEXT_RERENDER__(NewComponent) if the root is already mounted, otherwise falls back to a fresh hydrateRoot.

The endpoint /__bunext_client_hmr__?href=<page-url> handles on-demand HMR bundle generation: it re-bundles the target page's component on every request so the freshly injected script always reflects the latest source.

The SSE controller for each connected client is tracked in global.HMR_CONTROLLERS, keyed by the page URL and its bundled artifact map entry. On disconnect, the controller is removed from the list.

Request Pipeline

Every incoming request is handled by Bun.serve() and routed as follows:

Request
  │
  ├── config.middleware({ req, url, server })
  │     Returns Response? → short-circuit, send response immediately
  │     Returns undefined → continue
  │
  ├── GET /__hmr                        → Open SSE stream for HMR (dev only)
  │
  ├── GET /__bunext_client_hmr__?href=  → On-demand HMR bundle for the given page URL (dev only)
  │
  ├── /api/*              → API route handler
  │     Matches src/pages/api/<path>.ts
  │     Checks content-length against maxRequestBodyMB / 10 MB default
  │     Calls module.default(ctx) → returns Response directly
  │
  ├── /public/*           → Serve static file from public/
  │
  ├── /favicon.*          → Serve favicon from public/
  │
  └── Everything else     → Server-side render a page
        [Production only] Check public/__bunext/cache/ for key = pathname + search
          Cache HIT  → return cached HTML with X-Bunext-Cache: HIT header
          Cache MISS → continue ↓
        1. Match route via FileSystemRouter
        2. Find bundled artifact in BUNDLER_CTX_MAP
        3. Import page module (with cache-busting timestamp in dev)
        4. Run module.server(ctx) for server-side data
        5. Resolve meta (static object or async function)
        6. renderToString(component) → inject into HTML template
        7. Inject window.__PAGE_PROPS__, hydration <script>, CSS <link>
        8. If module.config.cachePage or serverRes.cachePage → write to cache
        9. Return HTML response
        On error → render 404 or 500 error page

Server-rendered HTML includes:

window.__PAGE_PROPS__ — the serialized server function return value, read by hydrateRoot on the client.
A <script type="module" async> tag pointing to the page's bundled client script.
A <link rel="stylesheet"> tag if the bundler emitted a CSS file for the page.
In development: the HMR client script.

29 KiB Raw Blame History