⚡ devstack

Ship your full-stack app in minutes, not days.

CLI scaffold generator that creates production-ready monorepo projects with
Bun, Turborepo, React 19, Hono, Drizzle ORM, and PostgreSQL.

bunx devstack

Getting Started · Stack Models · Modules · AI Layer · Contributing

🧐 Why devstack?

Every new project starts the same way — days wiring up linters, formatters, auth, payments, Docker, CI, database migrations… devstack eliminates that entirely. Run one command, pick your stack and modules, and get a production-grade monorepo with everything already connected.

Every generated project also ships with an AI agent intelligence layer — pre-configured CLAUDE.md and skill files that give Claude Code (and other AI agents) deep context about your project's architecture, conventions, and tooling.

✨ Features

• 🏗️ Two stack models — separated API + SPA or fullstack SSR
• 🧩 9 optional modules — auth, payments, email, storage, background jobs, and more
• 🔧 Production-ready defaults — Oxlint, Oxfmt, Vitest, Husky, Conventional Commits, GitHub Actions
• 🐳 Docker Compose infra — PostgreSQL, Redis, MinIO, Inngest, Mailpit — all pre-configured
• 🤖 AI-native projects — CLAUDE.md with skill dispatch protocol, architecture docs, agent skills
• 📦 Template overlays — modules contribute files, env vars, Docker services, and deps that merge cleanly

🚀 Getting Started

Prerequisites

| Requirement | Version | | --------------------------------------------- | -------- | | Bun | >= 1.2.0 | | Docker | Latest | | Git | Any |

Usage

# Run the interactive CLI
bunx devstack

# Follow the prompts:
#   1. App name (e.g., my-saas)
#   2. Target directory
#   3. Stack model (Separated or TanStack Start)
#   4. Optional modules
#   5. Install dependencies (yes/no)
#   6. Initialize git (yes/no)

# Start building
cd my-saas
docker compose up -d
bun run dev

🏗️ Stack Models

Choose the architecture that fits your project:

Separated (Hono API + Vite React)

Two packages with a clear boundary between frontend and backend:

packages/
├── frontend/   # React 19 + Vite + TanStack Router + Tailwind v4
└── backend/    # Hono + Drizzle ORM + PostgreSQL + Zod OpenAPI

React 19, Vite 8, TanStack Router (file-based), TanStack Query, Zustand, shadcn/ui (50+ components), Tailwind v4 with oklch color tokens, dark mode.

Hono v4 with Zod OpenAPI, Scalar API docs, Drizzle ORM, LogTape logging, Prometheus metrics, structured error handling. Follows a route → usecase → repository layered architecture.

TanStack Start (Fullstack SSR)

Single package with server functions and SSR:

packages/
└── app/
    ├── src/routes/    # File-based routes (UI + API)
    └── server/        # Server-only code (db, lib)

Same UI layer (shadcn/ui, Tailwind v4, TanStack Query) with server functions replacing the separate API.

🧩 Modules

All modules are optional — pick any combination during scaffolding:

| Module | What it adds | | --------------------- | ------------------------------------------------------- | | 🔐 Authentication | Better Auth with email/password sessions | | 🏢 Organizations | Multi-tenant org membership and roles (requires Auth) | | 💳 Stripe | Plans, subscriptions, and webhook handling | | 📁 Storage | S3/MinIO object storage with presigned URLs | | 📧 Email | Resend + SMTP fallback + React Email templates | | ⚙️ Inngest | Background jobs with local dev server | | 📡 Observability | OpenTelemetry tracing + Sentry error tracking | | 🔴 Redis | Redis client + rate limiting middleware | | 📖 Storybook | Component documentation workspace + Chromatic |

Modules declare dependencies — selecting Organizations automatically includes Authentication. Each module contributes:

• Environment variables (.env.example + Zod-validated env.ts)
• Docker Compose services
• Package dependencies (merged into the correct package.json)
• Template files (overlaid onto the base project)
• CLAUDE.md sections and agent skill files

📂 Generated Project Structure

A project generated with the Separated stack and Auth + Stripe modules:

my-saas/
├── packages/
│   ├── frontend/              # React 19 SPA
│   │   ├── src/
│   │   │   ├── components/    # shadcn/ui + app components
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   ├── lib/           # Utilities, API client
│   │   │   ├── routes/        # TanStack Router (file-based)
│   │   │   └── stores/        # Zustand stores
│   │   └── vite.config.ts
│   └── backend/               # Hono API
│       ├── src/
│       │   ├── modules/       # Feature modules (items, auth, billing)
│       │   ├── plugins/       # Hono middleware (error, logging, metrics)
│       │   ├── db/            # Drizzle schema + migrations
│       │   ├── lib/           # Auth client, Stripe client
│       │   └── env.ts         # Zod-validated environment
│       └── drizzle.config.ts
├── .claude/
│   ├── settings.json          # Allowed/denied commands for Claude Code
│   └── skills/                # Agent skill files
├── .github/
│   └── workflows/ci.yaml      # PR validation + make check
├── docker-compose.yaml         # PostgreSQL + module services
├── turbo.json                  # Turborepo task graph
├── Makefile                    # check, test, lint, fmt, db-reset
├── CLAUDE.md                   # AI agent instructions
└── AGENTS.md                   # Same as CLAUDE.md (for Codex)

🔧 Generated Tooling

Every generated project includes a battle-tested toolchain:

| Tool | Purpose | | -------------------------------------------------------- | ------------------------------------------ | | Bun | Package manager and runtime | | Turborepo | Monorepo task orchestration | | Oxlint | Fast linting (zero warnings policy) | | Oxfmt | Fast formatting | | Vitest | Unit and integration testing | | Husky + lint-staged | Pre-commit hooks | | Commitlint | Conventional Commits enforcement | | GitHub Actions | CI pipeline (PR title + make check) | | Docker Compose | PostgreSQL, Redis, MinIO, Inngest, Mailpit |

🤖 AI Agent Intelligence Layer

Generated projects are designed to work seamlessly with AI coding agents:

| Layer | What it provides | | -------------------------------------- | ----------------------------------------------------------------------------------------- | | CLAUDE.md / AGENTS.md | Architecture overview, coding conventions, skill enforcement rules, and dispatch protocol | | Skill files (.claude/skills/) | Domain-specific knowledge (React, Hono, Drizzle, Stripe, etc.) | | Settings (.claude/settings.json) | Pre-approved safe commands and blocked destructive operations |

[!TIP] The skill set is stack-aware: the Separated stack includes the hono skill while TanStack Start includes tanstack-start-best-practices. Module-specific skills are added based on your selections (e.g., better-auth-best-practices, stripe-webhooks).

🤝 Contributing

We welcome contributions! Here's how to get started:

Setup

git clone https://github.com/pedronauck/devstack.git
cd devstack
git submodule update --init --recursive
bun install

Commands

bun run dev              # Run the CLI interactively
bun run test             # Run tests (Vitest)
bun run typecheck        # Type-check with tsc
bun run lint             # Format check (Oxfmt) + lint (Oxlint)
bun run format           # Format all files
make check               # Full pipeline: format + lint-fix + typecheck + test

src/
├── cli.ts               # Interactive prompts (@clack/prompts)
├── generator.ts         # Core scaffolding engine
├── index.ts             # Entry point
├── builders/
│   ├── shared.ts        # Shared builders (Docker Compose, CLAUDE.md, Makefile)
│   ├── tanstack-start.ts # TanStack Start generation
│   └── types.ts         # GenerateContext type
├── modules/
│   ├── types.ts         # ModuleDefinition, MODULE_ORDER, skill types
│   ├── index.ts         # MODULE_REGISTRY
│   └── *.ts             # One file per module (auth, stripe, storage, etc.)
└── utils/
    ├── files.ts         # File copy, template processing, oxfmt formatting
    ├── packages.ts      # package.json deep merge
    └── template.ts      # Token replacement ({{projectName}}, etc.)

templates/
├── base/                # Base project files (root, frontend, backend)
└── modules/             # Per-module template overlays

tests/                   # Vitest test suite
vendor/skills/           # Git submodule — agent skill source files

1. The CLI collects user choices (name, stack model, modules)
2. The resolver auto-includes transitive module dependencies
3. Base templates are copied to the target directory
4. Module template overlays are merged on top
5. Template tokens ({{projectName}}, etc.) are replaced in all text files
6. Dynamic files are generated (package.json, docker-compose.yaml, CLAUDE.md, env.ts, turbo.json)
7. Module package contributions are deep-merged into the correct package.json files
8. Agent skill files are copied based on stack model + selected modules
9. All generated files are formatted with Oxfmt
10. Optionally: bun install and git init with initial commit

Commit Convention

This project uses Conventional Commits:

feat: add new module
fix: correct template token replacement
refactor: extract shared builder functions
test: add integration tests for TanStack Start

📄 License

MIT © Pedro Nauck

Built with ❤️ by Pedro Nauck

⭐ If devstack saves you time, consider giving it a star!