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>` ## About
- 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.
## 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`. ## Commands
- `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.
## 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 # CLI commands exposed by the built package (used in consumer projects)
import { test, expect } from "bun:test"; bunext dev # Start dev server with HMR and file watcher
bunext build # Bundle all pages for production
test("hello world", () => { bunext start # Start production server from pre-built artifacts
expect(1).toBe(1);
});
``` ```
## 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 ### Key directories
import index from "./index.html" - `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({ ### Page module contract
routes: { Pages live in `src/pages/`. A page file may export:
"/": index, - Default export: React component receiving `ServerProps | StaticProps`
"/api/users/:id": { - `server`: `BunextPageServerFn` — runs server-side before rendering, return value becomes props
GET: (req) => { - `meta`: `BunextPageModuleMeta` — SEO/OG metadata
return new Response(JSON.stringify({ id: req.params.id })); - `head`: ReactNode — extra `<head>` content
},
},
},
// 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,
}
})
```
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 ### Bundler artifact tracking
<html> `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.
<body>
<h1>Hello, world!</h1>
<script type="module" src="./frontend.tsx"></script>
</body>
</html>
```
With the following `frontend.tsx`: ### Config
Consumer projects define `bunext.config.ts` at their project root. The `BunextConfig` type fields: `distDir`, `assetsPrefix`, `origin`, `globalVars`, `port`, `development`.
```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`.

639
README.md
View File

File diff suppressed because it is too large Load Diff

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": { "scripts": {
"dev": "tsc --watch", "dev": "tsc --watch",
"docker:dev": "cd envs/development && docker compose down && docker compose up --build", "build": "tsc"
"start": "cd envs/production && docker compose down && docker compose up -d --build",
"preview": "cd envs/preview && docker compose down && docker compose up -d --build"
}, },
"devDependencies": { "devDependencies": {
"@types/bun": "latest", "@types/bun": "latest",

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

@ -1,8 +1,8 @@
import { Command } from "commander"; import { Command } from "commander";
import grabConfig from "../../src/functions/grab-config"; import grabConfig from "../../functions/grab-config";
import init from "../../src/functions/init"; import init from "../../functions/init";
import type { BunextConfig } from "../../src/types"; import type { BunextConfig } from "../../types";
import allPagesBundler from "../../src/functions/bundler/all-pages-bundler"; import allPagesBundler from "../../functions/bundler/all-pages-bundler";
export default function () { export default function () {
return new Command("build") return new Command("build")
@ -23,12 +23,6 @@ export default function () {
allPagesBundler({ allPagesBundler({
exit_after_first_build: true, 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 { Command } from "commander";
import grabConfig from "../../src/functions/grab-config"; import grabConfig from "../../functions/grab-config";
import startServer from "../../src/functions/server/start-server"; import startServer from "../../functions/server/start-server";
import init from "../../src/functions/init"; import init from "../../functions/init";
import type { BunextConfig } from "../../src/types"; import type { BunextConfig } from "../../types";
export default function () { export default function () {
return new Command("dev") 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 { Command } from "commander";
import grabConfig from "../../src/functions/grab-config"; import grabConfig from "../../functions/grab-config";
import startServer from "../../src/functions/server/start-server"; import startServer from "../../functions/server/start-server";
import init from "../../src/functions/init"; import init from "../../functions/init";
export default function () { export default function () {
return new Command("start") 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) { export default async function allPagesBundler(params?: Params) {
const pages = grabAllPages({ exclude_api: true }); const pages = grabAllPages({ exclude_api: true });
const { ClientRootElementIDName, ClientRootComponentWindowName } = const { ClientRootElementIDName, ClientRootComponentWindowName } =
await grabConstants(); grabConstants();
const virtualEntries: Record<string, string> = {}; const virtualEntries: Record<string, string> = {};
const dev = isDevelopment(); const dev = isDevelopment();

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

@ -1,9 +1,5 @@
import type { Server } from "bun"; import type { Server } from "bun";
import type { import type { BunextServerRouteConfig, BunxRouteParams } from "../../types";
APIResponseObject,
BunextServerRouteConfig,
BunxRouteParams,
} from "../../types";
import grabRouteParams from "../../utils/grab-route-params"; import grabRouteParams from "../../utils/grab-route-params";
import grabConstants from "../../utils/grab-constants"; import grabConstants from "../../utils/grab-constants";
import grabRouter from "../../utils/grab-router"; import grabRouter from "../../utils/grab-router";
@ -13,14 +9,10 @@ type Params = {
server: Server; server: Server;
}; };
export default async function ({ export default async function ({ req, server }: Params): Promise<Response> {
req,
server,
}: Params): Promise<APIResponseObject | undefined> {
const url = new URL(req.url); const url = new URL(req.url);
const { MBInBytes, ServerDefaultRequestBodyLimitBytes } = const { MBInBytes, ServerDefaultRequestBodyLimitBytes } = grabConstants();
await grabConstants();
const router = grabRouter(); const router = grabRouter();
@ -28,13 +20,19 @@ export default async function ({
if (!match?.filePath) { if (!match?.filePath) {
const errMsg = `Route ${url.pathname} not found`; const errMsg = `Route ${url.pathname} not found`;
// console.error(errMsg);
return { return Response.json(
{
success: false, success: false,
status: 401,
msg: errMsg, msg: errMsg,
}; },
{
status: 401,
headers: {
"Content-Type": "application/json",
},
},
);
} }
const routeParams: BunxRouteParams = await grabRouteParams({ req }); const routeParams: BunxRouteParams = await grabRouteParams({ req });
@ -52,17 +50,25 @@ export default async function ({
size > config.maxRequestBodyMB * MBInBytes) || size > config.maxRequestBodyMB * MBInBytes) ||
size > ServerDefaultRequestBodyLimitBytes size > ServerDefaultRequestBodyLimitBytes
) { ) {
return { return Response.json(
{
success: false, success: false,
status: 413,
msg: "Request Body Too Large!", msg: "Request Body Too Large!",
}; },
{
status: 413,
headers: {
"Content-Type": "application/json",
},
},
);
} }
} }
const res: APIResponseObject = await module["default"]( const res: Response = await module["default"]({
routeParams as BunxRouteParams, ...routeParams,
); server,
} as BunxRouteParams);
return res; 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 handleWebPages from "./web-pages/handle-web-pages";
import handleRoutes from "./handle-routes"; import handleRoutes from "./handle-routes";
import isDevelopment from "../../utils/is-development"; import isDevelopment from "../../utils/is-development";
import grabConstants from "../../utils/grab-constants";
type Params = { type Params = {
dev?: boolean; dev?: boolean;
@ -19,6 +20,20 @@ export default async function (params?: Params): Promise<ServeOptions> {
try { try {
const url = new URL(req.url); 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()) { if (url.pathname === "/__hmr" && isDevelopment()) {
const referer_url = new URL( const referer_url = new URL(
req.headers.get("referer") || "", req.headers.get("referer") || "",
@ -69,14 +84,7 @@ export default async function (params?: Params): Promise<ServeOptions> {
} }
if (url.pathname.startsWith("/api/")) { if (url.pathname.startsWith("/api/")) {
const res = await handleRoutes({ req, server }); return await handleRoutes({ req, server });
return new Response(JSON.stringify(res), {
status: res?.status,
headers: {
"Content-Type": "application/json",
},
});
} }
if (url.pathname.startsWith("/public/")) { 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 { SRC_DIR } = grabDirNames();
const PAGE_FILE_RE = /\.(tsx?|jsx?|css)$/;
export default function watcher() { export default function watcher() {
watch( watch(
SRC_DIR, SRC_DIR,
@ -16,12 +14,7 @@ export default function watcher() {
}, },
async (event, filename) => { async (event, filename) => {
if (!filename) return; 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 (event !== "rename") return;
if (global.RECOMPILING) 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, routeParams,
}: LivePageDistGenParams) { }: LivePageDistGenParams) {
const { ClientRootElementIDName, ClientWindowPagePropsName } = const { ClientRootElementIDName, ClientWindowPagePropsName } =
await grabContants(); grabContants();
const { renderToString } = await import( const { renderToString } = await import(
path.join(process.cwd(), "node_modules", "react-dom", "server") 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; : undefined;
const Component = module.default as FC<any>; const Component = module.default as FC<any>;
const Head = module.head as FC<any>; const Head = module.Head as FC<any>;
const component = RootComponent ? ( const component = RootComponent ? (
<RootComponent {...serverRes}> <RootComponent {...serverRes}>

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

@ -8,12 +8,12 @@ import type {
BundlerCTXMap, BundlerCTXMap,
BunextConfig, BunextConfig,
GlobalHMRControllerObject, GlobalHMRControllerObject,
} from "./src/types"; } from "./types";
import type { FileSystemRouter, Server } from "bun"; import type { FileSystemRouter, Server } from "bun";
import init from "./src/functions/init"; import init from "./functions/init";
import grabDirNames from "./src/utils/grab-dir-names"; import grabDirNames from "./utils/grab-dir-names";
import build from "./commands/build"; import build from "./commands/build";
import type { BuildContext, BuildResult } from "esbuild"; import type { BuildContext } from "esbuild";
/** /**
* # Declare Global Variables * # 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 }; globalVars?: { [k: string]: any };
port?: number; port?: number;
development?: boolean; development?: boolean;
middleware?: (
params: BunextConfigMiddlewareParams,
) => Promise<Response | undefined> | Response | undefined;
};
export type BunextConfigMiddlewareParams = {
req: Request;
url: URL;
server: Server;
}; };
export type GetRouteReturn = { export type GetRouteReturn = {
@ -69,6 +78,7 @@ export type BunxRouteParams = {
* Intercept and Transform the response object * Intercept and Transform the response object
*/ */
resTransform?: (res: Response) => Promise<Response> | Response; resTransform?: (res: Response) => Promise<Response> | Response;
server?: Server;
}; };
export interface PostInsertReturn { export interface PostInsertReturn {
@ -146,7 +156,7 @@ export type BunextPageModule = {
default: FC<any>; default: FC<any>;
server?: BunextPageServerFn; server?: BunextPageServerFn;
meta?: BunextPageModuleMeta | BunextPageModuleMetaFn; meta?: BunextPageModuleMeta | BunextPageModuleMetaFn;
head?: FC<BunextPageHeadFCProps>; Head?: FC<BunextPageHeadFCProps>;
}; };
export type BunextPageModuleMetaFn = (params: { export type BunextPageModuleMetaFn = (params: {

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

@ -1,8 +1,5 @@
import path from "path"; export default function grabConstants() {
import grabConfig from "../functions/grab-config"; const config = global.CONFIG;
export default async function grabConstants() {
const config = await grabConfig();
const MB_IN_BYTES = 1024 * 1024; const MB_IN_BYTES = 1024 * 1024;
const ClientWindowPagePropsName = "__PAGE_PROPS__"; const ClientWindowPagePropsName = "__PAGE_PROPS__";
@ -20,5 +17,6 @@ export default async function grabConstants() {
ServerDefaultRequestBodyLimitBytes, ServerDefaultRequestBodyLimitBytes,
ClientRootComponentWindowName, ClientRootComponentWindowName,
MaxBundlerRebuilds, MaxBundlerRebuilds,
config,
} as const; } 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 type { BunxRouteParams } from "../types";
import deserializeQuery from "./deserialize-query"; import deserializeQuery from "./deserialize-query";
@ -26,6 +25,7 @@ export default async function grabRouteParams({
url, url,
query, query,
body, body,
server: global.SERVER,
}; };
return routeParams; return routeParams;

2
tsconfig.json
View File

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