Epic 3 — Starter, docs & release
Make the convention reachable: a scaffolder template that lays out a working modular app, docs that make the choice between patties' two front doors obvious, and a feature (minor) release. No rename, no deprecation — this adds a feature.
Goal
bun create patties --template modular scaffolds a working modular monolith; the docs explain when to reach for it; patties ships a minor version with the new convention.
Definition of done
- A
modulartemplate increate-patties(two example modules + a shared_platform) that installs and passesvalidate. - Docs page(s): the module convention, the boundary rule, and when to use it vs the file-based full-stack surface.
- The agent skills (
_claude/_codex) updated so agents know the convention and the boundary rule. - A minor changeset; Version Packages PR merged; published to npm
latest. - Presence confirmed directly on registry.npmjs.org — a green Release run is necessary but not sufficient.
Modular scaffolder template
Files: a new template under packages/create-patties/templates/, wired into the template picker. Stamps a minimal module tree that obeys the boundary rule.
bun create patties /tmp/svc --template modular
cd /tmp/svc && bun install && bun run validate
# app/billing/{index,routes,invoice.service}.ts
# app/orders/{index,routes,order.service}.ts (imports ../billing)
# app/_platform/{index,db}.tsDocs & examples
The "two front doors" risk recorded in Decisions bites here. The docs must frame the choice, not bury it.
| Reach for… | When |
|---|---|
| File-based full-stack surface | UI-first apps: pages, islands, SSR, the component catalog. |
Module convention + routes.ts | Service-heavy / API-first apps: many domains, strong internal boundaries. |
| Both, in one app | Allowed — they share the same build pipeline, server, and middleware. |
Release
Never hand-edit version — use a changeset. This is additive, so a minor bump. Stable-only flow. Published versions land on the live Release dashboard.
bun changeset # patties (+ create-patties for the template) → minor
# merge the Version Packages PR → publishes to latest; if Release doesn't auto-fire:
gh workflow run Release --ref master
npm view patties version # confirm on the live registryResult
Convention + boundary check → route macro → starter + docs → minor release. patties gains a modular-monolith convention built entirely on Bun primitives, and its existing surface is exactly as it was.