Describes the Next.js 16 template stack (React 19, Tailwind v4, Biome, Bun), conventions, and how to add pages/components. Use when doing greenfield work, scaffolding new features, or when the agent needs to understand project structure and conventions.
| Technology | Version | Notes |
|---|---|---|
| Next.js | 16 | App Router |
| React | 19 | React Compiler enabled |
| Tailwind CSS | v4 | PostCSS-based |
| Biome | 2.x | Lint + format (no ESLint/Prettier) |
| Bun | - | Package manager and runtime |
bun dev - development serverbun build - production buildbun start - production serverbun lint - run lint checksbun lint:fix - fix lint issuesbun format - format codebun type-check - TypeScript checksrc/
app/
layout.tsx # Root layout
page.tsx # Home route
globals.css # Tailwind + CSS variables
loading.tsx # Route-level loading UI
error.tsx # Route-level error boundary
not-found.tsx # 404 page
biome.json.// --- Auth ---) and rare complex-logic comments only.src/app/** and src/pages/**next/image not <img>, no <head> in pagesuseSortedClasses enforces class orderingApp Router: each route is a folder under src/app/ with a page.tsx:
src/app/
page.tsx → /
about/page.tsx → /about
blog/[slug]/page.tsx → /blog/:slug
page.tsx - default export, the route UI.
layout.tsx - optional, wraps child routes (shared chrome).
loading.tsx - optional, Suspense fallback for the route.
error.tsx - optional, error boundary (must be 'use client').
Before creating: Search for existing components that could be reused or extended. Avoid duplicating similar components.
Prefer components over inline JSX: Anything that can be reused (buttons, cards, form fields, layouts) should be a proper component, not raw markup in a page.
Structure (under src/components/):
src/components/
ui/ # Primitives: Button, Input, Card, Modal, etc.
features/ # Feature-specific: AuthForm, ProductCard, NavBar, etc.
src/app/dashboard/Chart.tsx).ui/. Feature compositions → features/.@import "tailwindcss"; in globals.css@theme inline { ... } using CSS variablesvar(--color-name) for semantic tokens (e.g. text-foreground)