This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

CloneForge

What This Is

A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — run /clone-website <url1> [<url2> ...].

Cursor-first: Prefer Cursor’s built-in browser MCP (cursor-ide-browser) when available. Also works with Claude Code, Codex, Copilot, Windsurf, and other agents listed in the README.

The default src/app/page.tsx is a CloneForge showcase landing. Replace it when cloning a target site.

Tech Stack

• Framework: Next.js 16 (App Router, React 19, TypeScript strict)
• UI: shadcn/ui (Base UI / Radix-style primitives, Tailwind CSS v4, cn() utility)
• Icons: Lucide React (default — will be replaced/supplemented by extracted SVGs)
• Styling: Tailwind CSS v4 with design tokens
• Runtime: Node.js 20+
• Deployment: Vercel

Commands

• npm run setup — Node check + install
• npm run dev — Start dev server
• npm run build — Production build
• npm run lint — ESLint check
• npm run typecheck — TypeScript check
• npm run check — Run lint + typecheck + build
• npm run sync:skills — Regenerate /clone-website for all platforms

Code Style

• TypeScript strict mode, no any
• Named exports, PascalCase components, camelCase utils
• Tailwind utility classes, no inline styles (except when matching extracted computed styles that Tailwind cannot express)
• 2-space indentation
• Responsive: mobile-first

Design Principles

• Pixel-perfect emulation — match the target's spacing, colors, typography exactly
• No personal aesthetic changes during emulation phase — match 1:1 first, customize later
• Real content — use actual text and assets from the target site, not placeholders
• Beauty-first — every pixel matters

Project Structure

src/
  app/              # Next.js routes
  components/       # React components
    ui/             # shadcn/ui primitives
    icons.tsx       # Extracted SVG icons as React components
  lib/
    utils.ts        # cn() utility (shadcn)
  types/            # TypeScript interfaces
  hooks/            # Custom React hooks
public/
  images/           # Downloaded images from target site
  videos/           # Downloaded videos from target site
  seo/              # Favicons, OG images, webmanifest
docs/
  research/         # Inspection output (design tokens, components, layout)
  design-references/ # Screenshots and visual references
scripts/            # setup + sync scripts

MOST IMPORTANT NOTES

• When launching parallel builder agents, prefer each teammate in their own worktree/branch; merge at the end and resolve conflicts with full pipeline context.
• After editing AGENTS.md, run bash scripts/sync-agent-rules.sh (or npm run sync:agents) to regenerate platform-specific instruction files.
• After editing .claude/skills/clone-website/SKILL.md, run node scripts/sync-skills.mjs (or npm run sync:skills).
• Credit upstream: see NOTICE.md (based on JCodesMore/ai-website-cloner-template).

Website Inspection Guide

How to Reverse-Engineer Any Website

This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.

Phase 1: Visual Audit

Screenshots to Capture

• Every distinct page — desktop, tablet, mobile
• Dark mode variants (if applicable)
• Light mode variants (if applicable)
• Key interaction states (hover, active, open menus, modals)
• Loading/skeleton states
• Empty states
• Error states

Design Tokens to Extract

• Colors — background, text (primary/secondary/muted), accent, border, hover, error, success, warning
• Typography — font family, sizes (h1-h6, body, caption, label), weights, line heights, letter spacing
• Spacing — padding/margin patterns (look for a scale: 4px, 8px, 12px, 16px, 24px, 32px, etc.)
• Border radius — buttons, cards, avatars, inputs
• Shadows/elevation — card shadows, dropdown shadows, modal overlay
• Breakpoints — when does the layout shift? (inspect with DevTools responsive mode)
• Icons — which icon library? custom SVGs? sizes?
• Avatars — sizes, shapes, fallback behavior
• Buttons — all variants (primary, secondary, ghost, icon-only, danger)
• Inputs — text fields, textareas, selects, checkboxes, toggles

Phase 2: Component Inventory

For each distinct UI component, document:

1. Name — what would you call this component?
2. Structure — what HTML elements / child components does it contain?
3. Variants — does it have different sizes, colors, or states?
4. States — default, hover, active, disabled, loading, error, empty
5. Responsive behavior — how does it change at different breakpoints?
6. Interactions — click, hover, focus, keyboard navigation
7. Animations — transitions, entrance/exit animations, micro-interactions

Common Components to Look For

• Navigation (top bar, sidebar, bottom bar)
• Cards / list items
• Buttons and links
• Forms and inputs
• Modals and dialogs
• Dropdowns and menus
• Tabs and segmented controls
• Avatars and user badges
• Loading skeletons
• Toast notifications
• Tooltips and popovers

Phase 3: Layout Architecture

• Grid system — CSS Grid? Flexbox? Fixed widths?
• Column layout — how many columns at each breakpoint?
• Max-width — main content area max-width
• Sticky elements — header, sidebar, floating buttons
• Z-index layers — navigation, modals, tooltips, overlays
• Scroll behavior — infinite scroll, pagination, virtual scrolling

Phase 4: Technical Stack Analysis

• Framework — React? Vue? Angular? Check __NEXT_DATA__, __NUXT__, ng-version
• CSS approach — Tailwind (utility classes), CSS Modules, Styled Components, Emotion, vanilla CSS
• State management — Redux (check DevTools), React Query, Zustand, Pinia
• API patterns — REST, GraphQL (check network tab for /graphql requests)
• Font loading — Google Fonts, self-hosted, system fonts
• Image strategy — CDN, lazy loading, srcset, WebP/AVIF
• Animation library — Framer Motion, GSAP, CSS transitions only

Phase 5: Documentation Output

After inspection, create these files in docs/research/:

1. DESIGN_TOKENS.md — All extracted colors, typography, spacing
2. COMPONENT_INVENTORY.md — Every component with structure notes
3. LAYOUT_ARCHITECTURE.md — Page layouts, grid system, responsive behavior
4. INTERACTION_PATTERNS.md — Animations, transitions, hover states
5. TECH_STACK_ANALYSIS.md — What the site uses and our chosen equivalents