Next.js Full-Stack Scaffold
To scaffold a production-grade Next.js 16 full-stack application with modern tooling and best practices, follow these steps systematically.
Prerequisites Check
Before scaffolding, verify the target directory:
-
Confirm the current working directory is where files should be generated
-
Check if directory is empty or if user wants to override existing files
-
Confirm user wants to proceed with scaffold generation
Step 1: Gather Project Information
Prompt the user for the following details using the AskUserQuestion tool:
-
Project name (for package.json)
-
Project description
-
Author name
Use sensible defaults if user prefers to skip.
Step 2: Create Folder Structure
Create the complete folder structure as defined in assets/folder-structure.txt . Generate all necessary directories by writing files to them (directories are created automatically).
Step 3: Generate Configuration Files
Create all configuration files in the project root. Consult references/stack-architecture.md for architectural guidance.
Essential Config Files
Generate these files using Write tool:
-
package.json - Use template from assets/templates/package.template.json , replacing placeholders
-
tsconfig.json - TypeScript config with strict mode and path aliases
-
next.config.ts - Next.js configuration with server actions
-
tailwind.config.ts - Tailwind v4 with dark mode and shadcn/ui colors
-
postcss.config.mjs - PostCSS with Tailwind plugin
-
eslint.config.mjs - ESLint v9 flat config
-
prettier.config.js - Prettier with Tailwind plugin
-
.gitignore - Standard Next.js ignore patterns
-
.env.example - Environment variable template
-
vitest.config.ts - Vitest test configuration
-
playwright.config.ts - Playwright E2E configuration
Step 4: Generate App Router Files
Create all Next.js app router files following RSC conventions.
Root Files
-
app/layout.tsx
-
Root layout with metadata and providers
-
app/page.tsx
-
Landing page
-
app/globals.css
-
Tailwind directives and CSS variables
Authentication Routes
-
app/(auth)/layout.tsx
-
Auth layout (centered)
-
app/(auth)/login/page.tsx
-
Login page with form
Protected Routes
-
app/(protected)/layout.tsx
-
Protected layout with auth check
-
app/(protected)/dashboard/page.tsx
-
Dashboard with stats
-
app/(protected)/profile/page.tsx
-
User profile page
-
app/(protected)/data/page.tsx
-
Data table page
API Routes
- app/api/data/route.ts
- Example API endpoint
Middleware
- middleware.ts
- Supabase auth middleware
Step 5: Generate UI Components
Create shadcn/ui components in components/ui/ :
- button.tsx , card.tsx , input.tsx , label.tsx , form.tsx , table.tsx , dropdown-menu.tsx , avatar.tsx
Create custom components:
-
components/providers.tsx
-
App providers with Toaster
-
components/layout/header.tsx
-
Header with navigation
-
components/layout/sidebar.tsx
-
Sidebar navigation
-
components/layout/nav.tsx
-
Navigation links
-
components/auth/login-form.tsx
-
Login form with RHF + Zod
-
components/auth/auth-button.tsx
-
Sign in/out button
-
components/dashboard/stats-card.tsx
-
Stats display card
-
components/dashboard/data-table.tsx
-
Interactive data table
All components must be TypeScript and accessible.
Step 6: Generate Lib Files
Create utility and action files:
Utilities
-
lib/utils.ts
-
cn() function and utilities
-
lib/prisma.ts
-
Prisma client singleton
Supabase Clients
-
lib/supabase/client.ts
-
Client-side Supabase client
-
lib/supabase/server.ts
-
Server-side Supabase client
-
lib/supabase/middleware.ts
-
Middleware helper
Server Actions (all must start with 'use server' )
-
lib/actions/auth.ts
-
signIn(), signOut()
-
lib/actions/user.ts
-
updateProfile()
-
lib/actions/data.ts
-
CRUD operations
Validation Schemas (Zod)
-
lib/validations/auth.ts
-
Login/signup schemas
-
lib/validations/user.ts
-
Profile update schema
-
lib/validations/data.ts
-
Data CRUD schemas
Step 7: Generate Prisma Schema
Create prisma/schema.prisma :
-
PostgreSQL datasource with connection pooling
-
User model (id, email, name, timestamps)
-
Item model (example data model with relations)
-
Proper indexes and constraints
Create prisma/seed.ts :
-
TypeScript seed script
-
Sample users and items
Step 8: Generate Tests
Create test files:
-
tests/unit/utils.test.ts
-
Unit test for utilities
-
tests/integration/auth.test.tsx
-
Integration test for auth
-
tests/e2e/login.spec.ts
-
E2E test for login flow
Step 9: Generate CI Workflow
Create .github/workflows/ci.yml :
-
Lint, type check, test, build jobs
-
Run on push and PR
Step 10: Generate README
Create comprehensive README.md with:
-
Project overview and tech stack
-
Prerequisites and installation steps
-
Environment setup instructions
-
Database setup (Prisma commands)
-
Development and testing commands
-
Deployment guide
-
Folder structure explanation
Step 11: Final Verification
After generating all files:
-
Confirm all files were created successfully
-
List the folder structure for user review
-
Provide next steps for installation and setup
Implementation Notes
TypeScript
-
All files must use TypeScript
-
Proper type annotations
-
No any types unless necessary
Server Components
-
Use Server Components by default
-
Only add "use client" when required for interactivity
Accessibility
-
Use shadcn/ui accessible components
-
Include ARIA labels
-
Ensure keyboard navigation
Security
-
Validate inputs with Zod
-
Use Server Actions for mutations
-
Never expose secrets to client
Consulting References
Throughout scaffolding:
-
Consult references/stack-architecture.md for patterns
-
Consult references/implementation-checklist.md to track progress
Completion
When finished:
-
Summarize what was created
-
List all major files and directories
-
Provide next steps
-
Offer to answer questions