Next.js Boilerplate Setup
Bootstrap a production-ready Next.js project with modern tooling.
When to Use
-
User asks to create a new Next.js project
-
User wants to set up a React app with Tailwind CSS
-
User needs shadcn/ui components
-
User wants to build an AI chat interface
-
Starting a fresh frontend project with modern tooling
Stack Overview
Layer Technology Purpose
Framework Next.js 14+ (App Router) React framework with SSR/SSG
Styling Tailwind CSS Utility-first CSS
Components shadcn/ui Accessible, customizable components
AI Chat assistant-ui Pre-built AI chat interface components
TypeScript Strict mode Type safety
Setup Process
Step 1: Create Next.js Project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" cd my-app
Flags explained:
-
--typescript : TypeScript support
-
--tailwind : Tailwind CSS pre-configured
-
--eslint : ESLint for code quality
-
--app : App Router (not Pages Router)
-
--src-dir : Use src/ directory structure
-
--import-alias : Clean imports with @/
Step 2: Initialize shadcn/ui
npx shadcn@latest init
Recommended configuration:
-
Style: Default
-
Base color: Slate (or user preference)
-
CSS variables: Yes
-
React Server Components: Yes
-
Import alias for components: @/components
-
Import alias for utils: @/lib/utils
Step 3: Add Common Components
npx shadcn@latest add button card input label npx shadcn@latest add dialog dropdown-menu npx shadcn@latest add form (includes react-hook-form + zod)
Step 4: Add assistant-ui (Optional - for AI Chat)
npx assistant-ui@latest create
Or manual installation:
pnpm add @assistant-ui/react @assistant-ui/react-markdown
Project Structure
src/ ├── app/ │ ├── layout.tsx # Root layout with providers │ ├── page.tsx # Home page │ ├── globals.css # Tailwind imports + custom styles │ └── (routes)/ # Route groups ├── components/ │ ├── ui/ # shadcn/ui components │ └── ... # Custom components ├── lib/ │ └── utils.ts # Utility functions (cn, etc.) └── hooks/ # Custom React hooks
Essential Configurations
tailwind.config.ts
shadcn/ui sets this up, but verify:
-
Dark mode: class strategy
-
Content paths include all component locations
-
CSS variables for theming
TypeScript (tsconfig.json)
Ensure strict mode:
{ "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }
ESLint
Add helpful rules to .eslintrc.json :
{ "extends": ["next/core-web-vitals"], "rules": { "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }] } }
Common Patterns
Layout with Theme Provider
// src/app/layout.tsx import { ThemeProvider } from "@/components/theme-provider"
export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en" suppressHydrationWarning> <body> <ThemeProvider attribute="class" defaultTheme="system" enableSystem> {children} </ThemeProvider> </body> </html> ) }
cn() Utility Usage
import { cn } from "@/lib/utils"
<div className={cn( "base-styles", condition && "conditional-styles", className )} />
Form Pattern with react-hook-form + zod
import { useForm } from "react-hook-form" import { zodResolver } from "@hookform/resolvers/zod" import * as z from "zod"
const schema = z.object({ email: z.string().email(), })
function MyForm() { const form = useForm({ resolver: zodResolver(schema), }) // ... }
assistant-ui Integration
Basic Chat Setup
import { Thread } from "@assistant-ui/react" import { useVercelAIRuntime } from "@assistant-ui/react-ai-sdk" import { useChat } from "ai/react"
export function Chat() { const chat = useChat({ api: "/api/chat" }) const runtime = useVercelAIRuntime(chat)
return <Thread runtime={runtime} /> }
API Route (App Router)
// src/app/api/chat/route.ts import { openai } from "@ai-sdk/openai" import { streamText } from "ai"
export async function POST(req: Request) { const { messages } = await req.json() const result = await streamText({ model: openai("gpt-4o"), messages, }) return result.toDataStreamResponse() }
Verification Checklist
After setup, verify:
-
pnpm dev starts without errors
-
Tailwind styles apply correctly
-
shadcn/ui Button renders properly
-
Dark mode toggle works (if added)
-
TypeScript has no errors: pnpm tsc --noEmit
-
ESLint passes: pnpm lint
Common Issues
Tailwind Not Working
-
Check globals.css has Tailwind directives
-
Verify tailwind.config.ts content paths
-
Restart dev server after config changes
shadcn/ui Component Not Found
npx shadcn@latest add [component-name]
Hydration Mismatch
Add suppressHydrationWarning to <html> tag when using theme providers.
Import Errors
Verify tsconfig.json paths match shadcn/ui init choices.
Quick Reference Commands
Development
pnpm dev
Build
pnpm build
Type check
pnpm tsc --noEmit
Lint
pnpm lint
Add shadcn component
npx shadcn@latest add [name]
List available components
npx shadcn@latest add
When NOT to Use This Stack
-
Simple static sites (use Astro or plain HTML)
-
Apps requiring different styling approach (CSS Modules, styled-components)
-
Non-React projects
-
When the user has an existing project with different tooling