Vibecode Template

A full-stack TypeScript starter built for vibecoding with AI agents: describe what you want in plain language, and the agent builds it following the rules in AGENTS.md. Works with zero configuration — no database, no accounts, no env vars needed to start.

Stack

Piece	What it does
Next.js 16 (App Router) + React 19	The app — pages, layouts, server components
Bun	Package manager and runtime (bun --bun next ...)
tRPC v11 + Zod 4	End-to-end typesafe API with validated inputs
Mongoose 9 / MongoDB	Database — with an automatic in-memory fallback
Tailwind v4 + shadcn/ui	Styling and UI components, light/dark/system theme
nuqs	Search, filters and pages live in the URL (reload/back/share safe)
react-hook-form + Zod	Forms that share their validation schema with the API
Context7 MCP	Preconfigured in .mcp.json so agents fetch current library docs

Built for speed out of the box: Next.js Cache Components (static shell served instantly, dynamic parts stream in), partial prefetching, the React Compiler, streaming tRPC responses, a navigation progress bar, and skeleton loading states.

Quick start

Click Use this template on GitHub (or clone the repo), then:

bun install
bun run dev

Open http://localhost:3000. The Notes demo on the homepage proves the whole chain works (UI → tRPC → Zod → Mongoose → MongoDB) with zero setup: when MONGODB_URI is empty, an in-memory MongoDB starts automatically. The very first start downloads a MongoDB binary — give it a minute; after that it's instant.

When you start building the real app, delete the demo: src/components/notes-demo.tsx, src/trpc/routers/notes.ts, src/lib/schemas/note.ts, src/server/models/note.ts (and their usages in page.tsx / _app.ts).

Environment

Copy the example and fill in what you need:

cp .env.example .env

• MONGODB_URI — a real MongoDB connection string (e.g. MongoDB Atlas). Leave empty for the in-memory database — development only: data is lost on every restart, and on serverless every instance gets its own. Always set it in deployed environments.
• CONTEXT7_API_KEY — optional, raises the rate limits of the Context7 docs server (get one free). MCP clients read it from your shell environment, so also export it in your shell profile if you set one.

Scripts

Command	What it does
bun run dev	Dev server on the Bun runtime (Turbopack)
bun run build	Production build
bun run start	Serve the production build
bun run lint	ESLint
bun run typecheck	TypeScript check (tsc --noEmit)
bun run fmt	Format all files with Prettier
bun run fmt:check	Fail if any file is not formatted (CI)

GitHub Actions (.github/workflows/ci.yml) runs typecheck, lint, format check and build on every push. Dependabot (.github/dependabot.yml) opens one grouped pull request a week with dependency updates.

Deploy

Set MONGODB_URI on every deployed environment — without it each serverless instance spins up its own empty throwaway database.

This is a standard Next.js project, so platforms auto-detect everything, including Bun via bun.lock. The only platform file is vercel.json, which tells Vercel to use Bun 1.4 (older Bun crashes when loading Mongoose).

Vercel

Or push your copy to GitHub and import it at vercel.com/new. vercel.json makes Vercel install, build and run the app with Bun 1.4 (Vercel's Bun runtime is in public beta).

Railway

Create a project at railway.com/new and deploy from your repo — Railway detects Bun and runs the standard scripts. Add a MongoDB service (or use Atlas) and set MONGODB_URI.

Project structure

src/
  app/                    Pages & layouts (App Router)
    providers.tsx         Theme, progress bar, tRPC and nuqs providers
    loading.tsx           Skeleton shown while a page loads
    api/trpc/[trpc]/      The single tRPC HTTP handler
    globals.css           Tailwind v4 theme (CSS variables)
  server/
    db.ts                 Mongoose connection + in-memory fallback
    models/               One Mongoose model per file
  trpc/
    init.ts               tRPC setup, context, procedures
    routers/              One router per domain, merged in _app.ts
    client.tsx            Client provider + useTRPC hook
    server.tsx            Server-component helpers (prefetch, HydrateClient)
  components/             Shared components (components/ui is shadcn-managed)
    link.tsx              In-app link with instant navigation
    theme-picker.tsx      Light / Dark / System picker
    table-skeleton.tsx    Loading placeholder for tables
  lib/
    env.ts                Validated environment variables
    site.ts               App name and description
    schemas/              Zod schemas shared by forms and the API
    utils.ts              Shared utils (cn helper)

For AI agents

AGENTS.md is the rulebook (CLAUDE.md points to it): fetch current library docs via Context7 before coding, Bun-only workflows, security and code quality rules, and a completion checklist. This template deliberately ships without a test suite — verification is typecheck + lint + build + security review.