nextjs-boilerplate（Next.js boilerplate 前端）

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

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

1. Check globals.css has Tailwind directives
2. Verify tailwind.config.ts content paths
3. 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