nextjs-stack

Next.js Complete Stack

Master skill combining all framework documentation for modern Next.js development.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Analyze project structure and existing patterns
2. fuse-ai-pilot:research-expert - Verify latest docs for all stack technologies
3. mcp__context7__query-docs - Check integration compatibility

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

• Starting a new Next.js 16 project from scratch
• Need the complete recommended technology stack
• Building production applications with authentication
• Implementing forms, state management, and UI components
• Understanding how all parts fit together

Technology Stack

| Layer | Technology | Skill Reference | |-------|------------|-----------------| | Framework | Next.js 16 (App Router) | nextjs-16 | | Database ORM | Prisma 7 | prisma-7 | | Authentication | Better Auth 1.2 | better-auth | | UI Components | shadcn/ui 3.8.0 | nextjs-shadcn | | Forms | TanStack Form | nextjs-tanstack-form | | State | Zustand | nextjs-zustand | | Styling | Tailwind CSS 4 | tailwindcss | | i18n | next-intl 4.0 | nextjs-i18n |

Stack Decisions

Why These Technologies

| Choice | Reason | |--------|--------| | Better Auth over NextAuth.js | TypeScript-first, plugin system, self-hosted | | Prisma 7 over Drizzle | Mature ecosystem, migrations, studio | | TanStack Form over React Hook Form | Modern API, server actions, type safety | | Zustand over Redux/Context | Minimal boilerplate, SSR-friendly | | shadcn/ui over MUI/Chakra | Copy/paste ownership, Radix primitives |

Forbidden Patterns

• NextAuth.js - Use Better Auth instead
• Pages Router - Use App Router for new projects
• React Hook Form - Use TanStack Form
• Client Components by default - Server Components first

SOLID Architecture

Project Structure

src/
├── app/                    # Route handlers only
│   ├── [locale]/          # i18n routing
│   ├── api/               # API routes
│   └── layout.tsx         # Root layout
├── modules/
│   ├── cores/             # Shared infrastructure
│   │   ├── i18n/          # Internationalization
│   │   ├── shadcn/        # UI components
│   │   ├── lib/           # Utilities (cn, etc.)
│   │   └── db/            # Prisma client
│   ├── auth/              # Authentication module
│   └── [feature]/         # Feature modules
└── proxy.ts               # Route protection

Module Pattern

Each feature module contains:

• src/services/ - Business logic
• src/hooks/ - React hooks
• src/components/ - UI components
• src/interfaces/ - TypeScript types

Integration Points

Authentication + Database

Better Auth integrates with Prisma adapter for user storage. Schema in prisma/schema.prisma includes User, Session, Account, Verification tables.

Forms + UI + Validation

TanStack Form with Zod validation using shadcn/ui Field components. Server Actions for form submission.

State + Server Components

Zustand stores for client state only. Server Components fetch data directly. No global state for server data.

i18n + Routing

next-intl with [locale] segment. proxy.ts handles locale detection and redirects.

Quick Reference

Next.js 16

| Feature | Reference | |---------|-----------| | App Router | nextjs-16/app-router.md | | Server Components | nextjs-16/server-components.md | | Caching | nextjs-16/caching.md, cache-components.md | | proxy.ts | nextjs-16/proxy.md |

Prisma 7

| Feature | Reference | |---------|-----------| | Schema | prisma-7/schema.md | | Client | prisma-7/client.md | | Migrations | prisma-7/migrations.md | | TypedSQL | prisma-7/typed-sql.md |

Better Auth

| Feature | Reference | |---------|-----------| | Setup | better-auth/installation.md | | OAuth | better-auth/providers/ | | Plugins | better-auth/plugins/ | | Prisma adapter | better-auth/adapters/prisma.md |

Best Practices

1. Server Components default - Add 'use client' only when needed
2. Colocate code - Keep related code in feature modules
3. Type everything - Full TypeScript, no any
4. Fetch where used - No prop drilling for data
5. Validate at boundary - Zod schemas for all inputs
6. Cache explicitly - Use use cache directive

Getting Started

1. Review nextjs-16 for App Router fundamentals
2. Set up prisma-7 for database
3. Add better-auth for authentication
4. Install nextjs-shadcn components
5. Configure nextjs-i18n if multilingual
6. Add nextjs-zustand for client state