Moduletrace/bunext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update API routes function. Add middleware. Update README.md

Browse Source
This commit is contained in:
Benjamin Toby 2026-03-17 19:38:06 +01:00
parent ee1fb5897e
commit 35930857fd
20 changed files with 747 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
CLAUDE.md
View File

@ -1,106 +1,55 @@
# CLAUDE.md
Default to using Bun instead of Node.js.
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
- Use `bun test` instead of `jest` or `vitest`
- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
- Bun automatically loads .env, so don't use dotenv.
## About
## APIs
Bunext is a Next.js-style meta-framework built on Bun and React 19. It provides file-system routing, SSR, HMR, and static site generation, using ESBuild for client-side bundling and Bun.serve() as the HTTP server.
- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
- `Bun.redis` for Redis. Don't use `ioredis`.
- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
- `WebSocket` is built-in. Don't use `ws`.
- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
- Bun.$`ls` instead of execa.
## Commands
## Testing
```bash
# Build the TypeScript source (outputs to dist/)
bun run build # tsc
Use `bun test` to run tests.
# Watch mode for development of the framework itself
bun run dev # tsc --watch
```ts#index.test.ts
import { test, expect } from "bun:test";
test("hello world", () => {
expect(1).toBe(1);
});
# CLI commands exposed by the built package (used in consumer projects)
bunext dev # Start dev server with HMR and file watcher
bunext build # Bundle all pages for production
bunext start # Start production server from pre-built artifacts
```
## Frontend
## Architecture
Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
### Entry point
`src/index.ts` — Shebang CLI (`#!/usr/bin/env bun`). Uses Commander.js to dispatch `dev`, `build`, and `start` subcommands. Declares all global state (`global.CONFIG`, `global.ROUTER`, `global.BUNDLER_CTX`, `global.HMR_CONTROLLERS`, etc.).
Server:
### Command flow
- **`dev`**: init config → create FileSystemRouter → start ESBuild watch → start FS watcher → start Bun.serve() with HMR WebSocket
- **`build`**: init config → run allPagesBundler → exit after first successful build
- **`start`**: load `public/pages/map.json` (pre-built artifact map) → start Bun.serve() without bundler/watcher
```ts#index.ts
import index from "./index.html"
### Key directories
- `src/commands/` — CLI command implementations
- `src/functions/bundler/` — ESBuild bundler; uses a virtual namespace plugin to create per-page client hydration entry points and emits `map.json`
- `src/functions/server/` — Server startup, route dispatch, HMR watcher, rebuild logic, web-page rendering pipeline
- `src/utils/` — Stateless helpers (directory paths, router, config constants, JSON parser, etc.)
- `src/types/` — Shared TypeScript types
- `src/presets/` — Default 404/500 components and sample `bunext.config.ts`
Bun.serve({
routes: {
"/": index,
"/api/users/:id": {
GET: (req) => {
return new Response(JSON.stringify({ id: req.params.id }));
},
},
},
// optional websocket support
websocket: {
open: (ws) => {
ws.send("Hello, world!");
},
message: (ws, message) => {
ws.send(message);
},
close: (ws) => {
// handle close
}
},
development: {
hmr: true,
console: true,
}
})
```
### Page module contract
Pages live in `src/pages/`. A page file may export:
- Default export: React component receiving `ServerProps | StaticProps`
- `server`: `BunextPageServerFn` — runs server-side before rendering, return value becomes props
- `meta`: `BunextPageModuleMeta` — SEO/OG metadata
- `head`: ReactNode — extra `<head>` content
HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
API routes live in `src/pages/api/` and follow standard Bun `Request → Response` handler conventions.
```html#index.html
<html>
<body>
<h1>Hello, world!</h1>
<script type="module" src="./frontend.tsx"></script>
</body>
</html>
```
### Bundler artifact tracking
`BundlerCTXMap` (stored in `global.BUNDLER_CTX_MAP`) maps each page to its bundled output path, content hash, and entrypoint. In production this is serialized to `public/pages/map.json` and loaded at startup.
With the following `frontend.tsx`:
```tsx#frontend.tsx
import React from "react";
// import .css files directly and it works
import './index.css';
import { createRoot } from "react-dom/client";
const root = createRoot(document.body);
export default function Frontend() {
return <h1>Hello, world!</h1>;
}
root.render(<Frontend />);
```
Then, run index.ts
```sh
bun --hot ./index.ts
```
For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
### Config
Consumer projects define `bunext.config.ts` at their project root. The `BunextConfig` type fields: `distDir`, `assetsPrefix`, `origin`, `globalVars`, `port`, `development`.

639
README.md
View File

@ -1,23 +1,636 @@
# Bunext
A Next JS replacement built with bun JS and docker
A Next.js-style full-stack meta-framework built on [Bun](https://bun.sh) and React 19. Bunext provides server-side rendering, file-system based routing, Hot Module Replacement (HMR), and client-side hydration — using ESBuild to bundle client assets and Bun's native HTTP server (`Bun.serve`) to handle requests.
## Running this application
---
To run development:
## Table of Contents
```bash
bun dev
```
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Commands](#cli-commands)
- [Project Structure](#project-structure)
- [File-System Routing](#file-system-routing)
- [Pages](#pages)
- [Basic Page](#basic-page)
- [Server Function](#server-function)
- [Redirects from Server](#redirects-from-server)
- [Custom Response Options](#custom-response-options)
- [SEO Metadata](#seo-metadata)
- [Dynamic Metadata](#dynamic-metadata)
- [Custom Head Content](#custom-head-content)
- [Root Layout](#root-layout)
- [API Routes](#api-routes)
- [Route Config (Body Size Limit)](#route-config-body-size-limit)
- [Error Pages](#error-pages)
- [Static Files](#static-files)
- [Configuration](#configuration)
- [Middleware](#middleware)
- [Environment Variables](#environment-variables)
- [How It Works](#how-it-works)
- [Development Server](#development-server)
- [Production Build](#production-build)
- [Bundler](#bundler)
- [Hot Module Replacement](#hot-module-replacement)
- [Request Pipeline](#request-pipeline)
To run production:
```bash
bun start
```
---
## Requirements
### Docker
- [Bun](https://bun.sh) v1.0 or later
- TypeScript 5.0+
- React 19 and react-dom 19 (peer dependencies)
You need `docker` installed to run this project
---
## Installation
Install Bunext as a dependency in your project:
```bash
bun add bunext
```
Install required peer dependencies:
```bash
bun add react react-dom
bun add -d typescript @types/react @types/react-dom
```
---
## Quick Start
1. Create a minimal project layout:
```
my-app/
├── src/
│ └── pages/
│ └── index.tsx
├── bunext.config.ts # optional
└── package.json
```
2. Create your first page (`src/pages/index.tsx`):
```tsx
export default function HomePage() {
return <h1>Hello from Bunext!</h1>;
}
```
3. Start the development server:
```bash
bunext dev
```
4. 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. |
```bash
# 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
│ └── pages/ # Generated by bundler (do not edit manually)
│ └── map.json # Artifact map used by production server
├── 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.
---
## Pages
### Basic Page
A page file must export a default React component. The component receives server-side props automatically.
```tsx
// 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.
```tsx
// src/pages/profile.tsx
import type { BunextPageServerFn } from "bunext/src/types";
type Props = {
props?: { username: string; bio: string };
query?: Record<string, string>;
};
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 }: Props) {
return (
<div>
<h1>{props?.username}</h1>
<p>{props?.bio}</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 |
### Redirects from Server
Return a `redirect` object from the `server` function to redirect the client:
```tsx
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:
```tsx
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>`:
```tsx
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:
```tsx
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:
```tsx
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:
```tsx
// 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`.
```ts
// 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:
```ts
// 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](#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):
```ts
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:
```tsx
// 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.*`.
---
## Configuration
Create a `bunext.config.ts` file in your project root to configure Bunext:
```ts
// 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 |
| `middleware` | `(params: BunextConfigMiddlewareParams) => Response \| undefined \| Promise<...>` | — | Global middleware — see [Middleware](#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.
```ts
// 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:
```ts
middleware: async ({ req, url }) => {
// Block a specific path
if (url.pathname === "/maintenance") {
return new Response("Down for maintenance", { status: 503 });
}
// Add CORS headers to all API responses
if (url.pathname.startsWith("/api/")) {
// Let the request proceed, but transform the response via resTransform on individual routes
}
},
```
---
## Environment Variables
| Variable | Description |
| -------- | ------------------------------------------------------- |
| `PORT` | Override the server port (takes precedence over config) |
---
## How It Works
### Development Server
Running `bunext dev`:
1. Loads `bunext.config.ts` and sets `development: true`.
2. Initializes directories (`.bunext/`, `public/pages/`).
3. Creates a `Bun.FileSystemRouter` pointed at `src/pages/`.
4. Starts the ESBuild bundler in **watch mode** — it will automatically rebuild when file content changes.
5. 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.
6. Waits for the first successful bundle.
7. Starts `Bun.serve()`.
### Production Build
Running `bunext build`:
1. Sets `NODE_ENV=production`.
2. Runs ESBuild once (not in watch mode) with minification enabled.
3. Writes all bundled artifacts to `public/pages/` and the artifact map to `public/pages/map.json`.
4. Exits.
### Production Server
Running `bunext start`:
1. Reads `public/pages/map.json` to load the pre-built artifact map.
2. 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 event through the SSE stream and the client reloads the page automatically.
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)
│
├── /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
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. 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" defer>` 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.

2
bunfig.toml
View File

@ -1,2 +0,0 @@
[serve.static]
plugins = ["bun-plugin-tailwind"]

132
info/how-it-works.md
View File

@ -1,132 +0,0 @@
Here's the full flow, start to finish:
---
1. Startup (index.ts → commands/dev/index.ts)
Running bun ../../index.ts dev:
- init() is called twice (once in index.ts, once in the dev command — redundant but harmless). It ensures all required
directories exist (src/pages/, .bunext/client/hydration-src/, public/pages/, etc.) and creates a blank bunext.config.ts
if missing.
- global.CONFIG is set with development: true.
- global.ROUTER is created as a Bun.FileSystemRouter pointing at src/pages/ using Next.js-style routing.
---
2. Initial Build (start-server.ts → allPagesBundler)
Before accepting requests, allPagesBundler() runs:
1. grabAllPages({ exclude_api: true }) — recursively walks src/pages/, skipping api/ routes and directories with ( or )
in the name, returning an array of { local_path, url_path, file_name }.
2. For each page, writeWebPageHydrationScript() generates a .tsx entrypoint in
.bunext/client/hydration-src/pageName.tsx. That file looks like:
import React from "react";
import { hydrateRoot } from "react-dom/client";
import App from "/absolute/path/to/src/pages/index.tsx";
const container = document.getElementById("bunext-root");
hydrateRoot(container, <App {...window.**BUNEXT_PAGE_PROPS**} />);
3. Stale hydration files (for deleted pages) are cleaned up.
4. bundle() runs bun build .bunext/client/hydration-src/\*.tsx --outdir public/pages/ --minify via execSync. Bun bundles
each entrypoint for the browser, outputting public/pages/pageName.js (and public/pages/pageName.css if any CSS was
imported).
---
3. Server Start (server-params-gen.ts)
Bun.serve() is called with a single fetch handler that routes by URL pathname:
┌─────────────────┬──────────────────────────┐
│ Path │ Handler │
├─────────────────┼──────────────────────────┤
│ /\_\_hmr │ SSE stream for HMR │
├─────────────────┼──────────────────────────┤
│ /api/_ │ handleRoutes │
├─────────────────┼──────────────────────────┤
│ /public/_ │ Static file from public/ │
├─────────────────┼──────────────────────────┤
│ /favicon.\* │ Static file from public/ │
├─────────────────┼──────────────────────────┤
│ Everything else │ handleWebPages (SSR) │
└─────────────────┴──────────────────────────┘
---
4. Incoming Page Request → handleWebPages
4a. Route matching (grab-page-component.tsx)
- A new Bun.FileSystemRouter is created from src/pages/ (in dev; in prod it uses the cached global.ROUTER).
- router.match(url.pathname) resolves the URL to an absolute file path (e.g. / → .../src/pages/index.tsx).
- grabRouteParams() builds a BunxRouteParams object containing req, url, query (deserialized from search params), and
body (parsed JSON for non-GET requests).
4b. Module import
const module = await import(`${file_path}?t=${global.LAST_BUILD_TIME ?? 0}`);
The ?t= cache-buster forces Bun to re-import the module after a rebuild instead of serving a stale cached version.
4c. server() function
If the page exports a server function, it's called with routeParams and its return value becomes serverRes — the props
passed to the component. This is the data-fetching layer (equivalent to Next.js getServerSideProps).
4d. Component instantiation
const Component = module.default as FC<any>;
const component = <Component {...serverRes} />;
The default export is treated as the page component, instantiated with the server-fetched props.
▎ If anything above throws (bad route, import error, etc.), the error path falls back to the /500 page (user-defined or
the preset).
---
5. HTML Generation (generate-web-html.tsx)
renderToString(component) is called — importing react-dom/server dynamically from process.cwd()/node_modules/ (the
consumer's React, avoiding the duplicate-instance bug).
The resulting HTML is assembled:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<link rel="stylesheet" href="/public/pages/index.css" /> <!-- if CSS exists -->
<script>/* HMR EventSource, dev only */</script>
</head>
<body>
<div id="bunext-root"><!-- renderToString output --></div>
<script>window.__BUNEXT_PAGE_PROPS__ = {...}</script>
<script src="/public/pages/index.js" type="module"></script>
</body>
</html>
The pageProps (from server()) are serialized via EJSON and injected as window.**BUNEXT_PAGE_PROPS** so the client
hydration script can read them without an extra network request.
---
6. Client Hydration (browser)
The browser:
1. Parses the server-rendered HTML and displays it immediately (no blank flash).
2. Loads /public/pages/index.js (the Bun-bundled client script).
3. That script calls hydrateRoot(container, <App {...window.**BUNEXT_PAGE_PROPS**} />) — React attaches event handlers
to the existing DOM rather than re-rendering from scratch.
At this point the page is fully interactive.
---
7. HMR (dev only)
The injected EventSource("/\_\_hmr") maintains a persistent SSE connection. When the watcher detects a file change, it
rebuilds all pages, updates LAST_BUILD_TIME, and sends event: update\ndata: reload down the SSE stream. The browser
calls window.location.reload(), which re-requests the page and repeats steps 4–6 with the fresh module.

4
package.json
View File

@ -12,9 +12,7 @@
],
"scripts": {
"dev": "tsc --watch",
"docker:dev": "cd envs/development && docker compose down && docker compose up --build",
"start": "cd envs/production && docker compose down && docker compose up -d --build",
"preview": "cd envs/preview && docker compose down && docker compose up -d --build"
"build": "tsc"
},
"devDependencies": {
"@types/bun": "latest",

14
commands/build/index.ts → src/commands/build/index.ts
View File

@ -1,8 +1,8 @@
import { Command } from "commander";
import grabConfig from "../../src/functions/grab-config";
import init from "../../src/functions/init";
import type { BunextConfig } from "../../src/types";
import allPagesBundler from "../../src/functions/bundler/all-pages-bundler";
import grabConfig from "../../functions/grab-config";
import init from "../../functions/init";
import type { BunextConfig } from "../../types";
import allPagesBundler from "../../functions/bundler/all-pages-bundler";
export default function () {
return new Command("build")
@ -23,12 +23,6 @@ export default function () {
allPagesBundler({
exit_after_first_build: true,
// async post_build_fn({ artifacts }) {
// writeFileSync(
// HYDRATION_DST_DIR_MAP_JSON_FILE,
// JSON.stringify(artifacts),
// );
// },
});
});
}

8
commands/dev/index.ts → src/commands/dev/index.ts
View File

@ -1,8 +1,8 @@
import { Command } from "commander";
import grabConfig from "../../src/functions/grab-config";
import startServer from "../../src/functions/server/start-server";
import init from "../../src/functions/init";
import type { BunextConfig } from "../../src/types";
import grabConfig from "../../functions/grab-config";
import startServer from "../../functions/server/start-server";
import init from "../../functions/init";
import type { BunextConfig } from "../../types";
export default function () {
return new Command("dev")

6
commands/start/index.ts → src/commands/start/index.ts
View File

@ -1,7 +1,7 @@
import { Command } from "commander";
import grabConfig from "../../src/functions/grab-config";
import startServer from "../../src/functions/server/start-server";
import init from "../../src/functions/init";
import grabConfig from "../../functions/grab-config";
import startServer from "../../functions/server/start-server";
import init from "../../functions/init";
export default function () {
return new Command("start")

2
src/functions/bundler/all-pages-bundler.ts
View File

@ -41,7 +41,7 @@ type Params = {
export default async function allPagesBundler(params?: Params) {
const pages = grabAllPages({ exclude_api: true });
const { ClientRootElementIDName, ClientRootComponentWindowName } =
await grabConstants();
grabConstants();
const virtualEntries: Record<string, string> = {};
const dev = isDevelopment();

56
src/functions/server/handle-routes.ts
View File

@ -1,9 +1,5 @@
import type { Server } from "bun";
import type {
APIResponseObject,
BunextServerRouteConfig,
BunxRouteParams,
} from "../../types";
import type { BunextServerRouteConfig, BunxRouteParams } from "../../types";
import grabRouteParams from "../../utils/grab-route-params";
import grabConstants from "../../utils/grab-constants";
import grabRouter from "../../utils/grab-router";
@ -13,14 +9,10 @@ type Params = {
server: Server;
};
export default async function ({
req,
server,
}: Params): Promise<APIResponseObject | undefined> {
export default async function ({ req, server }: Params): Promise<Response> {
const url = new URL(req.url);
const { MBInBytes, ServerDefaultRequestBodyLimitBytes } =
await grabConstants();
const { MBInBytes, ServerDefaultRequestBodyLimitBytes } = grabConstants();
const router = grabRouter();
@ -28,13 +20,19 @@ export default async function ({
if (!match?.filePath) {
const errMsg = `Route ${url.pathname} not found`;
// console.error(errMsg);
return {
success: false,
status: 401,
msg: errMsg,
};
return Response.json(
{
success: false,
msg: errMsg,
},
{
status: 401,
headers: {
"Content-Type": "application/json",
},
},
);
}
const routeParams: BunxRouteParams = await grabRouteParams({ req });
@ -52,17 +50,25 @@ export default async function ({
size > config.maxRequestBodyMB * MBInBytes) ||
size > ServerDefaultRequestBodyLimitBytes
) {
return {
success: false,
status: 413,
msg: "Request Body Too Large!",
};
return Response.json(
{
success: false,
msg: "Request Body Too Large!",
},
{
status: 413,
headers: {
"Content-Type": "application/json",
},
},
);
}
}
const res: APIResponseObject = await module["default"](
routeParams as BunxRouteParams,
);
const res: Response = await module["default"]({
...routeParams,
server,
} as BunxRouteParams);
return res;
}

24
src/functions/server/server-params-gen.ts
View File

@ -5,6 +5,7 @@ import grabDirNames from "../../utils/grab-dir-names";
import handleWebPages from "./web-pages/handle-web-pages";
import handleRoutes from "./handle-routes";
import isDevelopment from "../../utils/is-development";
import grabConstants from "../../utils/grab-constants";
type Params = {
dev?: boolean;
@ -19,6 +20,20 @@ export default async function (params?: Params): Promise<ServeOptions> {
try {
const url = new URL(req.url);
const { config } = grabConstants();
if (config?.middleware) {
const middleware_res = await config.middleware({
req,
url,
server,
});
if (typeof middleware_res == "object") {
return middleware_res;
}
}
if (url.pathname === "/__hmr" && isDevelopment()) {
const referer_url = new URL(
req.headers.get("referer") || "",
@ -69,14 +84,7 @@ export default async function (params?: Params): Promise<ServeOptions> {
}
if (url.pathname.startsWith("/api/")) {
const res = await handleRoutes({ req, server });
return new Response(JSON.stringify(res), {
status: res?.status,
headers: {
"Content-Type": "application/json",
},
});
return await handleRoutes({ req, server });
}
if (url.pathname.startsWith("/public/")) {

7
src/functions/server/watcher.tsx
View File

@ -5,8 +5,6 @@ import rebuildBundler from "./rebuild-bundler";
const { SRC_DIR } = grabDirNames();
const PAGE_FILE_RE = /\.(tsx?|jsx?|css)$/;
export default function watcher() {
watch(
SRC_DIR,
@ -16,12 +14,7 @@ export default function watcher() {
},
async (event, filename) => {
if (!filename) return;
const file_path = path.join(SRC_DIR, filename);
// if (!PAGE_FILE_RE.test(filename)) return;
// "change" events (file content modified) are already handled by
// esbuild's internal ctx.watch(). Only "rename" (create or delete)
// requires a full rebuild because entry points have changed.
if (event !== "rename") return;
if (global.RECOMPILING) return;

2
src/functions/server/web-pages/generate-web-html.tsx
View File

@ -16,7 +16,7 @@ export default async function genWebHTML({
routeParams,
}: LivePageDistGenParams) {
const { ClientRootElementIDName, ClientWindowPagePropsName } =
await grabContants();
grabContants();
const { renderToString } = await import(
path.join(process.cwd(), "node_modules", "react-dom", "server")

2
src/functions/server/web-pages/grab-page-component.tsx
View File

@ -125,7 +125,7 @@ export default async function grabPageComponent({
: undefined;
const Component = module.default as FC<any>;
const Head = module.head as FC<any>;
const Head = module.Head as FC<any>;
const component = RootComponent ? (
<RootComponent {...serverRes}>

8
index.ts → src/index.ts
View File

@ -8,12 +8,12 @@ import type {
BundlerCTXMap,
BunextConfig,
GlobalHMRControllerObject,
} from "./src/types";
} from "./types";
import type { FileSystemRouter, Server } from "bun";
import init from "./src/functions/init";
import grabDirNames from "./src/utils/grab-dir-names";
import init from "./functions/init";
import grabDirNames from "./utils/grab-dir-names";
import build from "./commands/build";
import type { BuildContext, BuildResult } from "esbuild";
import type { BuildContext } from "esbuild";
/**
* # Declare Global Variables

0
bunext.config.ts → src/presets/bunext.config.ts
View File

12
src/types/index.ts
View File

@ -48,6 +48,15 @@ export type BunextConfig = {
globalVars?: { [k: string]: any };
port?: number;
development?: boolean;
middleware?: (
params: BunextConfigMiddlewareParams,
) => Promise<Response | undefined> | Response | undefined;
};
export type BunextConfigMiddlewareParams = {
req: Request;
url: URL;
server: Server;
};
export type GetRouteReturn = {
@ -69,6 +78,7 @@ export type BunxRouteParams = {
* Intercept and Transform the response object
*/
resTransform?: (res: Response) => Promise<Response> | Response;
server?: Server;
};
export interface PostInsertReturn {
@ -146,7 +156,7 @@ export type BunextPageModule = {
default: FC<any>;
server?: BunextPageServerFn;
meta?: BunextPageModuleMeta | BunextPageModuleMetaFn;
head?: FC<BunextPageHeadFCProps>;
Head?: FC<BunextPageHeadFCProps>;
};
export type BunextPageModuleMetaFn = (params: {

8
src/utils/grab-constants.ts
View File

@ -1,8 +1,5 @@
import path from "path";
import grabConfig from "../functions/grab-config";
export default async function grabConstants() {
const config = await grabConfig();
export default function grabConstants() {
const config = global.CONFIG;
const MB_IN_BYTES = 1024 * 1024;
const ClientWindowPagePropsName = "__PAGE_PROPS__";
@ -20,5 +17,6 @@ export default async function grabConstants() {
ServerDefaultRequestBodyLimitBytes,
ClientRootComponentWindowName,
MaxBundlerRebuilds,
config,
} as const;
}

2
src/utils/grab-route-params.ts
View File

@ -1,4 +1,3 @@
import type { Server } from "bun";
import type { BunxRouteParams } from "../types";
import deserializeQuery from "./deserialize-query";
@ -26,6 +25,7 @@ export default async function grabRouteParams({
url,
query,
body,
server: global.SERVER,
};
return routeParams;

2
tsconfig.json
View File

@ -17,6 +17,6 @@
"noPropertyAccessFromIndexSignature": false,
"outDir": "dist"
},
"include": ["src", "commands", "index.ts"],
"include": ["src", "commands", "src/index.ts"],
"exclude": ["node_modules", "dist"]
}