Patties Framework — Overview

Mission

Patties is a Bun-native full-stack meta-framework with React for UI and Bun's own Bun.serve for HTTP, in a single bun dev command, deployable to the edge without configuration.

Pillars (non-negotiable)

Bun-native — use Bun primitives (Bun.serve, Bun.Glob, Bun.build, bun --hot). Never reach for Node.js http, chokidar, webpack, or vite. No HTTP framework dependency — Bun.serve({ routes }) is the router.
Standard Web APIs at the boundary — handlers receive a Request, return a Response. A thin framework-owned ctx carries params, cookies (Bun.CookieMap), env, and the AI context.
React for rendering — server uses react-dom/server (renderToReadableStream); islands use react-dom/client (hydrateRoot). Bun runs both natively; we never reach for Node-only React APIs like renderToPipeableStream.
Edge-first, vendor-neutral — the default deploy artifact is a portable WinterCG / workerd-style Worker module (export default { fetch }). It runs on any compliant edge runtime — Cloudflare Workers, Deno Deploy, Vercel Edge, Netlify Edge, Bun's own edge runtime, etc. The framework picks no vendor; vendor-specific deploy lives in plugins.
AI-native — agents and MCP tools are first-class directories, not plugins. AGENTS.md is generated on every build.

Non-goals

Compatibility with the next import surface.
Node.js as a runtime target. Supported targets are bun and edge.
Bundling vendor-specific deploy config (wrangler.toml, vercel.json, deno.json, netlify.toml) into the framework core. Those live in deploy plugins so we never become a Cloudflare-only — or any-single-vendor — framework.
A custom bundler — Bun.build is the only bundler.
A custom file watcher — bun --watch is the only watcher.

Package layout

Patties ships as a single npm package (patties) with subpath exports:

patties — createServer, createRouter, createRenderer, core types.
patties/config — defineConfig, config schema.
patties/ai — defineAgent, defineTool, getAgent, getTool, streamText, streamObject, createAiContext.
patties/client — createClient, hydration runtime.
patties/plugin — definePlugin, plugin types.

One package, one version, one changelog. No @patties/* scope at launch.

Subsystem map

Spec	File	Replaces
01-server	`server/index.ts`	`http.createServer`, Hono
02-router	`router/index.ts`	Next router, Hono
02b-filesystem-router	`router/filesystem.ts`	`fast-glob`
03-render	`server/render.tsx`	— (uses `react-dom/server`)
04-build	`build/index.ts`	webpack/vite config
05-dev-hmr	`dev/watcher.ts`	`chokidar`
06-client-islands	`client/index.ts`	— (uses `react-dom/client`)
07-middleware	`app/middleware.ts`	Next middleware
08-config	`patties.config.ts`	`next.config.js`
09-plugins	`plugins/index.ts`	Next plugin system
10-agents-and-tools	`app/agents/`, `app/tools/`	— (net new)
11-agents-md-generator	build step	— (net new)
12-edge-adapters	adapters	— (net new)
13-conventions	repo-wide	—
14-testing	`tests/fixtures/`	—
15-claude-code-scaffold	`CLAUDE.md`, `.claude/` (opt-in)	— (net new)
17-dev-island-bundler	`src/dev/bundler.ts` (planned)	— (net new; design decision)
18-dev-island-bundler-impl	`src/dev/bundler.ts` (planned)	— (net new; implementation of 17)

Phase alignment

Phase 0 ships: 01, 02, 02b, 03, 13 (minimal), 15 (scaffold contents).
Phase 1 ships: 04, 05, 06, 07, 14.
Phase 2 ships: 08, 12.
Phase 3 ships: 10, 11.
Phase 4 ships: 09.
Dev-DX (post-launch): 17 (decision), 18 (impl), 26 (monorepo React single-copy resolution — prerequisite for create-patties --monorepo, cli/18), 27 (patties run task runner + output cache — encodes rfc-bun-task-cache) — see framework/draft/.