bunext/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

About

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.

Commands

# Build the TypeScript source (outputs to dist/)
bun run build       # tsc

# Watch mode for development of the framework itself
bun run dev         # tsc --watch

# 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
bunext sitemap      # Write public/sitemap.xml and public/robots.txt using config.sitemap / config.robots

Architecture

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.).

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

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

Page module contract

Pages live in src/pages/. Server logic is separated from page files into companion .server.ts / .server.tsx files to avoid bundling server-only code into the client.

Page file (page.tsx) — client-safe exports only (bundled to the browser):

• Default export: React component receiving props from the server file
• meta: BunextPageModuleMeta — SEO/OG metadata
• Head: FC — extra <head> content
• config: BunextRouteConfig — cache settings
• html_props: BunextHTMLProps — attributes on the <html> element

Server file (page.server.ts or page.server.tsx) — server-only, never sent to the browser:

• Default export or export const server: BunextPageServerFn — runs server-side before rendering, return value becomes props
• export const sitemap: BunextPageSitemapFn — optional; returns the page's sitemap entries (how dynamic routes get into bunext sitemap)

The framework resolves the companion by replacing the page extension with .server.ts or .server.tsx. If neither exists, no server function runs and only the default url prop is injected.

__root.tsx follows the same contract; its server companion is __root.server.ts.

API routes live in src/pages/api/ and follow standard Bun Request → Response handler conventions.

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. bunext build also updates .bunext/page-lastmod.json (src/utils/page-lastmod-record.ts): per page, a fingerprint of the bundle hash + CSS path and the build date it last changed. The sitemap uses these dates as lastmod.

Config

Consumer projects define bunext.config.ts at their project root. The BunextConfig type fields include dist_dir, assets_prefix, origin, global_vars, port, development.

The dist directory (default .bunext) is resolved by setupDistDir() (src/functions/setup-dist-dir.ts): --dist-dir > BUNEXT_DIST_DIR env > config dist_dir. It runs in the CLI's preAction hook and at the start of bunextInit() (so custom servers get it too), and stores the result in BUNEXT_DIST_DIR, which grabDirNames() reads and child processes inherit. Because it runs after modules are imported, never read a dist-derived path from grabDirNames() at module level — call it inside the function that uses it. Only root-derived paths (ROOT_DIR, PAGES_DIR, PUBLIC_DIR, ...) may be read at module level; src/__tests__/utils/grab-dist-dir.test.ts enforces this. Client bundle URLs are their project-relative paths (grabBunextPublicUrlPath()), so never hard-code /.bunext in URLs or paths.