tools-only 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: Usesrc/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:
classstrategy - 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 devstarts 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.csshas Tailwind directives - Verify
tailwind.config.tscontent 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