Archived cli/archive/05-create-patties.md

create-patties Scaffolder

bunx create-patties my-app produces a new Patties project that runs immediately with bun dev. This is the developer's first impression of the framework; it m…

Purpose

bunx create-patties my-app produces a new Patties project that runs immediately with bun dev. This is the developer's first impression of the framework; it must be flawless.

Package

Lives in packages/create-patties/ (separate package from patties itself). Distributed on npm so bunx create-patties resolves it.

Usage

bunx create-patties <name> [--template <name>] [--target bun|edge]
                           [--deploy cloudflare|vercel|deno|netlify|bun|none]
                           [--agent claude-code|none]
                           [--no-install] [--no-git]

Interactive prompts

When run in a TTY without all flags supplied, prompt for the missing ones:

  1. Template — default / with-islands / ai-starter.
  2. Deploy target — bun (self-hosted / long-running) / edge (portable Worker module). The framework picks no vendor at this step.
  3. Deploy plugin (only when target=edge) — cloudflare / vercel / deno / netlify / none (just emit the portable artifact). Installs the matching @patties/deploy-<choice> and adds it to patties.config.ts plugins.
  4. AI coding agent — claude-code / none.
    • Question text: "Will you use Claude Code on this project? We'll scaffold a CLAUDE.md and a .claude/ directory tuned for Patties."
    • Default: none (so the no-prompt path stays neutral and reproducible).

Non-TTY runs require flags; unanswered prompts fall back to defaults silently.

Behavior

  1. Validate <name> as a legal directory and npm package name.
  2. If the directory exists and is non-empty, refuse with a clear message.
  3. Copy the chosen template (default if unspecified) into ./<name>/.
  4. Rewrite package.json#name to <name>.
  5. Set the target in patties.config.ts to the chosen value (default bun).
  6. If --agent claude-code: scaffold the Claude-Code-specific files per framework spec 15-claude-code-scaffold — namely CLAUDE.md at the project root and a .claude/ directory with settings.json, commands/, and agents/ seeded for Patties.
  7. If --agent none: do not create CLAUDE.md or .claude/. AGENTS.md is still auto-generated by the first patties build (framework 11) regardless of this choice.
  8. Unless --no-install, run bun install in the new directory.
  9. Unless --no-git, run git init && git add -A && git commit -m "chore: initial commit from create-patties".
  10. Print next-step instructions: `` cd <name> bun dev ` If --agent claude-code was chosen, append: ` Claude Code is configured. Open the project and run claude to start a session. ``

Templates

  • default — one page, no islands, no agents. The Phase 0 success-signal app.
  • with-islands — adds a counter island.
  • ai-starter — adds one agent and one MCP tool (Phase 3+).

Templates live in packages/create-patties/templates/<name>/. Each is a real, runnable Patties project; CI builds and runs each one on every PR to catch drift.

Agent-tooling matrix

ChoiceAGENTS.mdCLAUDE.md.claude/
--agent none (default)generated on first patties build——
--agent claude-codegenerated on first patties buildscaffolded immediatelyscaffolded immediately

AGENTS.md is the open, vendor-neutral context file — every project gets one. CLAUDE.md and .claude/ are Claude-Code-specific tooling and only ship when the developer opts in.

Acceptance criteria

  • bunx create-patties foo && cd foo && bun dev ends with a working page on localhost:3000.
  • Re-running bunx create-patties foo in the same directory fails without overwriting anything.
  • The generated project's AGENTS.md (after first build) lists exactly the seed route.
  • bunx create-patties foo --agent claude-code produces foo/CLAUDE.md and foo/.claude/ matching framework spec 15. --agent none produces neither.
  • The interactive prompt for "AI coding agent" appears in a TTY when --agent is not passed, and never blocks in a non-TTY.