Next.js Project Setup

> **Skill Purpose:** Complete Next.js App Router initialization patterns for Zeus framework projects

Coverage-Creatives/zeus·0installs0stars

SKILL.md

Full skill instructions

Next.js Project Setup

Skill Purpose: Complete Next.js App Router initialization patterns for Zeus framework projects

Overview

This skill provides the complete patterns for initializing a Next.js project using App Router, configured specifically for the Zeus framework with all required tooling and structure.

Prerequisites

Node.js 18+ installed
npm or package manager available
Project directory identified

Step-by-Step Patterns

1. Initialize Next.js Project

# Create new Next.js project with App Router
npx create-next-app@latest [project-name] --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

# Navigate to project directory
cd [project-name]

2. Configure TypeScript Settings

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/app/*": ["./src/app/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

3. Configure Package.json Scripts

Update package.json scripts section:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

4. Set Up Directory Structure

Create the following directory structure:

src/
├── app/
│   ├── (auth)/
│   ├── api/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ui/
│   └── forms/
├── lib/
│   ├── utils.ts
│   └── validations.ts
├── types/
│   └── index.ts
└── middleware.ts

5. Configure Environment Variables

Create .env.example:

# Database
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

# Auth
NEXTAUTH_SECRET=
NEXTAUTH_URL=

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

Create .env.local (gitignored):

# Local development values
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

6. Update Next.js Configuration

Update next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['@supabase/supabase-js'],
  },
  images: {
    domains: ['your-supabase-project.supabase.co'],
  },
  env: {
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  },
};

export default nextConfig;

7. Configure Prettier

Create .prettierrc:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}

Create .prettierignore:

.next/
node_modules/
build/
dist/

8. Update ESLint Configuration

Update .eslintrc.json:

{
  "extends": ["next/core-web-vitals", "@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "warn",
    "prefer-const": "error"
  }
}

9. Create Basic Layout Structure

Update src/app/layout.tsx:

import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Zeus Framework App',
  description: 'Built with Zeus framework',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

10. Configure Git

Create .gitignore:

# Dependencies
node_modules/
.pnp
.pnp.js

# Production builds
.next/
out/
build/
dist/

# Environment variables
.env.local
.env.development.local
.env.test.local
.env.production.local

# Vercel
.vercel

# TypeScript
*.tsbuildinfo
next-env.d.ts

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*

Create .gitattributes:

# Auto detect text files and perform LF normalization
* text=auto eol=lf

# Explicitly declare text files you want to always be normalized and converted
# to native line endings on checkout.
*.js text eol=lf
*.jsx text eol=lf
*.ts text eol=lf
*.tsx text eol=lf
*.json text eol=lf
*.md text eol=lf

# Declare files that will always have CRLF line endings on checkout.
*.bat text eol=crlf
*.cmd text eol=crlf

# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.svg binary

Code Examples

Basic Page Component

// src/app/page.tsx
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm">
        <h1 className="text-4xl font-bold">
          Welcome to Zeus Framework
        </h1>
      </div>
    </main>
  );
}

Utility Function Example

// src/lib/utils.ts
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Configuration Templates

Package.json Dependencies

{
  "dependencies": {
    "next": "14.0.0",
    "react": "^18",
    "react-dom": "^18",
    "@supabase/supabase-js": "^2.38.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "postcss": "^8",
    "tailwindcss": "^3.3.0",
    "eslint": "^8",
    "eslint-config-next": "14.0.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "prettier": "^3.0.0"
  }
}

Best Practices

Always use App Router - Never use Pages Router for new projects
Use src directory - Keeps source code organized
Configure path aliases - Improves import readability
Set up strict TypeScript - Catches errors early
Configure environment variables - Never commit secrets
Use proper Git configuration - Ensures consistent line endings
Set up linting and formatting - Maintains code quality
Create proper directory structure - Follows Zeus conventions

Stop Conditions

STOP and report if:

Node.js version is below 18
create-next-app command fails
TypeScript configuration errors occur
Required directories cannot be created
Package installation fails
Git configuration fails

Expected Outcomes:

Next.js project initialized with App Router
TypeScript configured with strict mode
Path aliases working
Environment variables configured
Git repository initialized
All required directories created
Development server starts successfully

Verification Checklist

Next.js project created successfully
TypeScript compiles without errors
Development server starts (npm run dev)
Path aliases work (@/ imports)
ESLint runs without errors
Prettier formats correctly
Git repository initialized
Environment variables configured
Basic page loads in browser

Version: 1.0.0 Last Updated: 2026-01-31 Skill Category: Architecture - Scaffolding

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/Coverage-Creatives/zeus --skill nextjs-project-setup

View on GitHub

.windsurf/nextjs-project-setup/SKILL.md