Efficient Next.js Scaffold

Scaffold a complete Next.js application with optimized configuration, project structure, TypeScript setup, Tailwind CSS, ESLint, security headers, and production-ready defaults.

When to Use This Command

Run this command when you need to set up a new Next.js project with best-practice configuration from the start.

• You are starting a new Next.js project and want a production-ready scaffold
• You need optimized next.config.js with image formats, security headers, and package imports
• You want the App Router directory structure with layout, page, and API route templates
• You need TypeScript, Tailwind CSS, ESLint, and Prettier configured correctly together

Use it also when:

• You want Husky and lint-staged for pre-commit quality checks
• You need a scaffold that matches enterprise-grade project standards

Quick Start

Copy
# .claude/commands/efficient-nextjs-scaffold.md
name: efficient-nextjs-scaffold
description: Scaffold a production-ready Next.js app
arguments:
  name: Project name

Copy
# Create a new Next.js project
claude efficient-nextjs-scaffold "my-saas-app --typescript --tailwind"

Expected output:
Scaffolding: my-saas-app

  Created:
    app/layout.tsx          (root layout with metadata)
    app/page.tsx            (home page)
    app/globals.css         (Tailwind directives)
    app/api/health/route.ts (health check endpoint)
    components/ui/          (UI primitives directory)
    lib/                    (utilities directory)
    public/                 (static assets)
    next.config.js          (optimized configuration)
    tailwind.config.js      (Tailwind setup)
    tsconfig.json           (TypeScript strict mode)
    .eslintrc.json          (ESLint + Next.js rules)

  Next: cd my-saas-app && npm install && npm run dev

Core Concepts

Concept	Description
App Router	Next.js 13+ file-system routing via app/ directory
Root Layout	Required layout.tsx that wraps all pages with shared UI
Security Headers	X-Frame-Options, X-Content-Type-Options, CSP headers
Package Imports	optimizePackageImports for tree-shaking icon and utility libraries
Strict TypeScript	tsconfig.json with strict: true for maximum type safety

Project Structure:
  my-saas-app/
       │
       ├── app/           (routes, layouts, pages)
       │    ├── api/      (API route handlers)
       │    └── globals.css
       │
       ├── components/    (reusable React components)
       │    └── ui/       (primitive UI elements)
       │
       ├── lib/           (utilities, configs, helpers)
       ├── public/        (static files, favicons)
       ├── types/         (shared TypeScript types)
       └── next.config.js (production-optimized config)

Configuration

Parameter	Default	Description
name	required	Project directory name
typescript	true	Enable TypeScript with strict mode
tailwind	true	Include Tailwind CSS configuration
eslint	true	Include ESLint with Next.js recommended rules
husky	false	Set up Husky + lint-staged for pre-commit hooks

Best Practices

1. Start with the scaffold, then customize -- The scaffold provides sensible defaults. Adjust next.config.js, tailwind.config.js, and tsconfig.json to match your specific needs.

2. Keep the component/ui directory for primitives -- Place foundational UI elements (Button, Input, Card) in components/ui/ and composed features in components/features/.

3. Use the lib directory for non-React code -- Database clients, API helpers, validation schemas, and utility functions belong in lib/, not components/.

4. Enable image optimization formats -- The scaffold configures WebP and AVIF formats. Ensure your deployment platform supports these formats in production.

5. Review security headers for your use case -- The default X-Frame-Options: DENY prevents iframe embedding. Change to SAMEORIGIN if you need iframe support for your own domain.

Common Issues

1. Directory already exists -- The scaffold will not overwrite an existing directory. Choose a unique project name or remove the existing directory first.

2. Node.js version incompatibility -- Next.js 14+ requires Node.js 18.17+. Check your version with node --version before scaffolding.

3. Tailwind styles not applying -- Ensure app/globals.css includes the Tailwind directives (@tailwind base; @tailwind components; @tailwind utilities;) and is imported in layout.tsx.