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:

1. Confirm the current working directory is where files should be generated
2. Check if directory is empty or if user wants to override existing files
3. 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:

1. Confirm all files were created successfully
2. List the folder structure for user review
3. 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:

1. Summarize what was created
2. List all major files and directories
3. Provide next steps
4. Offer to answer questions