nextjs-stack · diff
git:20260207.0a3cd21 to git:20260705.8c2f9bc
13 added, 113 removed. Audit A to A.
---
name: nextjs-stack
- description: Next.js 16+ complete stack with App Router, Prisma 7, Better Auth, shadcn/ui, TanStack Form, Zustand. Use as the master reference combining all framework skills.
+ description: Next.js 16+ complete stack with App Router, Prisma 7, Better Auth, shadcn/ui, TanStack Form, Zustand. Use as the master reference combining all framework skills. Do NOT use for: core framework API details — routing, caching, Server Components internals, proxy.ts (use nextjs-16 and its references).
versions:
nextjs: 16
react: 19
prisma: 7
better-auth: 1.2
shadcn-ui: 3.8.0
tailwindcss: 4
user-invocable: true
related-skills: nextjs-16, prisma-7, better-auth, nextjs-shadcn, nextjs-tanstack-form, nextjs-zustand, nextjs-i18n, solid-nextjs
---
# 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
+ ## 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
+ ## References
- ---
+ Detailed guidance lives in `references/` to keep this file scannable — load only what the task needs:
- ## Getting Started
+ | File | Load when… |
+ |------|------------|
+ | [references/stack-decisions.md](references/stack-decisions.md) | Justifying a technology choice (Better Auth vs NextAuth, Prisma vs Drizzle, TanStack Form vs RHF, Zustand vs Redux, shadcn/ui vs MUI) |
+ | [references/solid-architecture.md](references/solid-architecture.md) | Setting up or reviewing the project's module/folder structure |
+ | [references/integration-points.md](references/integration-points.md) | Wiring two parts of the stack together (auth+DB, forms+UI, state+RSC, i18n+routing) |
+ | [references/quick-reference.md](references/quick-reference.md) | Looking up which sub-skill file covers a specific feature (App Router, Prisma schema, Better Auth OAuth, …) |
+ | [references/best-practices.md](references/best-practices.md) | Doing a final review pass before shipping |
+ | [references/getting-started.md](references/getting-started.md) | Bootstrapping a brand-new project step by step |
- 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
+ For framework-specific detail, go directly to the sub-skill: `nextjs-16`, `prisma-7`, `better-auth`, `nextjs-shadcn`, `nextjs-tanstack-form`, `nextjs-zustand`, `nextjs-i18n`, `solid-nextjs`.