create-bunship
Scaffold a production-ready Bun monorepo in one command — and ship it. Instead of maintaining its own boilerplate, bunship orchestrates each framework's official scaffolder non-interactively, then wires a single coherent toolchain on top.
bun create bunship my-startup # interactive
# or, fully non-interactive (AI-agent mode):
bunx create-bunship my-startup --web next --api nest --docker --cicd --jsonSupported frameworks
Pick at most one per slot (none skips a slot). Apps are generated by the framework's
own scaffolder, so they always match upstream output.
| Slot | Framework | Flag | Scaffolded with | Dir | Dev port |
|---|---|---|---|---|---|
| Web | Next.js | --web next |
create-next-app |
apps/web |
3000 |
| Web | React + Vite | --web react-vite |
create-vite (react-ts) |
apps/web |
5173 |
| Web | Nuxt | --web nuxt |
create-nuxt |
apps/web |
3000 |
| Mobile | Expo | --mobile expo |
create-expo-app |
apps/mobile |
8081 |
| API | NestJS | --api nest |
@nestjs/cli (nest new) |
apps/api |
3001 |
| API | Express | --api express |
built-in minimal TS template | apps/api |
3001 |
| API | Hono | --api hono |
create-hono (bun template) |
apps/api |
3001 |
| API | Fastify | --api fastify |
fastify generate (ts) |
apps/api |
3001 |
Each app is then patched to fit the monorepo: workspace package name
(@<project>/<app>), non-conflicting dev ports, a /health endpoint on API stacks, and
formatting normalized with oxfmt.
What you get after running it
my-startup/
├── apps/
│ ├── web/ your chosen web framework (official scaffolder output)
│ ├── mobile/ Expo (if selected)
│ └── api/ your chosen API framework
├── package.json bun workspaces + scripts (below), engines pinned to Bun 1.3
├── .oxlintrc.json linting (oxlint)
├── .oxfmtrc.json formatting (oxfmt)
├── knip.json unused files / exports / deps
├── .husky/ pre-commit lint-staged · pre-push full check
├── .vscode/ settings + recommended extensions
├── AGENTS.md + CLAUDE.md conventions for AI coding agents
├── .gitignore · .gitattributes · .env.example · README.md
│
│ with --docker:
├── apps/*/Dockerfile per-app production images
├── compose.yaml local prod-parity: docker compose up --build
│
│ with --cicd (implies --docker):
├── .github/workflows/ ci.yml (check + build) · deploy.yml (GHCR → SSH → compose)
└── deploy/ VPS bundle: image-based compose, nginx + TLS, bootstrap guideThe generated root package.json gives you:
| Script | Does |
|---|---|
bun run dev |
all dev servers via workspace filter |
bun run dev:web / dev:api |
one app (one script per selected app) |
bun run build |
build every app |
bun run check |
lint + format:check + typecheck + knip |
bun run lint / format |
oxlint / oxfmt (with :fix / :check variants) |
The CLI finishes by running git init, bun install, an oxfmt pass, and a first commit
— so every generated repo passes bun run check and bun run build from its very first
commit (enforced by this project's nightly CI matrix against latest upstream scaffolders).
Flags
| Flag | Meaning |
|---|---|
--web <next|react-vite|nuxt|none> |
Web frontend |
--mobile <expo|none> |
Mobile app |
--api <nest|express|hono|fastify|none> |
API backend |
--docker / --no-docker |
Dockerfiles + compose.yaml |
--cicd / --no-cicd |
GitHub Actions CI + VPS deploy pipeline (implies docker) |
--json |
Agent mode: no prompts, stdout is exactly one JSON manifest |
-y, --yes |
Defaults: next + nest + docker + cicd |
--dry-run |
Print the manifest without writing anything |
--no-git, --no-install, --force, --verbose, --keep-on-error |
What they say |
Agent mode
--json makes the CLI a good citizen for AI coding agents: all progress goes to stderr,
stdout carries a single JSON manifest (apps, ports, scripts, required deploy secrets, next
steps), exit codes are meaningful (0 ok / 1 pipeline / 2 usage), and the generated repo
contains an AGENTS.md so agents don't re-derive conventions. Boilerplate comes from
official scaffolders, not from model output — that's the whole point.
Requires Bun ≥ 1.3 on PATH (plus git, unless --no-git). The CLI itself runs under
Node ≥ 20 (npx-compatible).