home / skills / petekp / claude-code-setup / nextjs-boilerplate

nextjs-boilerplate skill

safe

/skills/nextjs-boilerplate

This skill bootstraps a production-ready Next.js project with Tailwind, shadcn/ui, and assistant-ui for AI chat interfaces.

npx playbooks add skill petekp/claude-code-setup --skill nextjs-boilerplate

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.1 KB

---
name: nextjs-boilerplate
description: Bootstrap a new Next.js development environment with Tailwind CSS, shadcn/ui components, and assistant-ui for AI chat interfaces. Use when the user asks to "create a new Next.js project", "bootstrap Next.js with shadcn", "set up a Next.js app", "create an AI chat app", "start a new React project with Tailwind", or mentions creating a fresh frontend project with modern tooling.
---

# 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

```bash
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

```bash
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

```bash
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)

```bash
npx assistant-ui@latest create
```

Or manual installation:

```bash
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:

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}
```

### ESLint

Add helpful rules to `.eslintrc.json`:

```json
{
  "extends": ["next/core-web-vitals"],
  "rules": {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
  }
}
```

## Common Patterns

### Layout with Theme Provider

```tsx
// 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

```tsx
import { cn } from "@/lib/utils"

<div className={cn(
  "base-styles",
  condition && "conditional-styles",
  className
)} />
```

### Form Pattern with react-hook-form + zod

```tsx
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

```tsx
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)

```tsx
// 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

```bash
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

```bash
# 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

Overview

This skill bootstraps a production-ready Next.js app configured with Tailwind CSS, shadcn/ui components, and assistant-ui for AI chat interfaces. It creates a TypeScript-first project using the App Router, strict typing, provider-ready layout, and sensible defaults so you can focus on features instead of build tooling. Use it to start modern frontend projects or add an AI chat surface quickly.

How this skill works

The skill runs the recommended create-next-app command with flags for TypeScript, Tailwind, ESLint, App Router, and a src directory, then initializes shadcn/ui and optionally installs assistant-ui. It scaffolds component folders, a theme-enabled root layout, Tailwind and TypeScript configs, and example chat and API route code for streaming AI responses. It also provides a checklist and common commands to verify the setup.

When to use it

You want to create a new Next.js project with modern defaults
You need Tailwind CSS and utility-first styling out of the box
You plan to use shadcn/ui for accessible, composable UI components
You want a ready-made AI chat interface using assistant-ui
You need a strict TypeScript setup with sensible ESLint rules

Best practices

Run create-next-app with --typescript --tailwind --app --src-dir --import-alias for clean imports
Enable strict TypeScript and noUncheckedIndexedAccess to catch issues early
Use ThemeProvider in root layout and set suppressHydrationWarning on <html> to avoid hydration mismatches
Add shadcn components via npx shadcn@latest add to keep UI consistent and discoverable
Verify Tailwind content paths and restart dev server after config changes

Example use cases

Bootstrapping a new product dashboard with consistent design system and theme support
Building an AI chat prototype using assistant-ui and a streaming API route
Creating forms with react-hook-form and zod using shadcn form components
Starting a developer-facing app that needs strict TypeScript and ESLint rules
Spinning up a demo app to showcase component library and dark mode toggles

FAQ

Do I have to use pnpm?

No. The scaffolding works with npm, pnpm, or yarn. Example commands use pnpm by convention, but swap package manager commands as needed.

How do I connect the chat to a real model?

Implement an API route that forwards messages to your chosen runtime (Vercel AI, OpenAI, Anthropic, etc.) and return a streaming response; the example POST route shows the pattern.