A production-oriented starter for rebuilding live websites as typed Next.js applications with AI coding agents. The template ships a strict TypeScript toolchain, optional Redis-backed session persistence, and multi-platform agent skills so /clone-website workflows stay reproducible across teams.

Start from your own copy. Use GitHub Use this template to create a separate repository. Do not commit generated clone output back to this upstream template.

• Why this template
• System architecture
• Clone workflow
• Features
• Requirements
• Installation
• Configuration
• Development
• Testing
• Project structure
• Troubleshooting
• Contributing
• FAQ
• License

Most website rebuilds fail in the handoff between design extraction and component implementation. This repository standardizes that boundary:

flowchart TB
  subgraph agents [AI Coding Agents]
    CC[Claude Code]
    CX[Codex / Cursor / Copilot]
    Others[Gemini / Windsurf / ...]
  end

  subgraph template [Template Repository]
    SKILL["/clone-website skill"]
    AGENTS[AGENTS.md rules]
    APP[Next.js App Router]
    CACHE[Cache layer]
    API["/api/cache/*"]
  end

  subgraph persistence [Optional Persistence]
    MEM[(In-memory store)]
    REDIS[(Redis)]
  end

  subgraph output [Generated Clone]
    COMP[React components]
    ASSETS[public/images + seo]
    SPECS[docs/research/components]
  end

  agents --> SKILL
  SKILL --> AGENTS
  AGENTS --> APP
  APP --> API
  API --> CACHE
  CACHE --> MEM
  CACHE --> REDIS
  SKILL --> SPECS
  SPECS --> COMP
  SKILL --> ASSETS

sequenceDiagram
  participant Agent
  participant API as /api/cache/sessions
  participant Service as CacheService
  participant Backend as Memory or Redis

  Agent->>API: POST session metadata
  API->>Service: saveCloneSession()
  Service->>Backend: SET session:{id}
  Backend-->>Service: OK
  Service-->>API: session record
  API-->>Agent: 201 Created

  Agent->>API: GET ?id=session-1
  API->>Service: getCloneSession()
  Service->>Backend: GET session:{id}
  Backend-->>Service: JSON payload
  Service-->>API: CloneSessionRecord
  API-->>Agent: 200 OK

flowchart LR
  A[Reconnaissance] --> B[Foundation]
  B --> C[Component specs]
  C --> D[Parallel builders]
  D --> E[Assembly and QA]

  A --- A1[Screenshots + tokens]
  B --- B1[Fonts, globals, assets]
  C --- C1[docs/research/components]
  D --- D1[Git worktrees per section]
  E --- E1[Visual diff + merge]

Run inside your agent:

/clone-website https://example.com

Phases are defined in .claude/skills/clone-website/SKILL.md and propagated to other platforms via npm run sync:skills.

• Strict TypeScript — noUnusedLocals, no allowJs, separate configs for app, scripts, and tests
• Optional Redis persistence — connection manager with retry, graceful shutdown, and typed config
• In-memory fallback — zero external services required for local development
• Cache HTTP API — health probe and clone-session CRUD at /api/cache/*
• Multi-platform skills — one skill source, nine generated platform targets
• Docker Compose stack — app, dev, and Redis services with health checks
• CI pipeline — lint, typecheck, test, and build on every push

# 1. Create your repository from the GitHub template UI

# 2. Clone your copy
git clone https://github.com/YOUR-ORG/YOUR-REPO.git
cd YOUR-REPO

# 3. Install dependencies (lockfile is local-only)
npm install

# 4. Copy environment defaults
cp .env.example .env

# 5. Start the dev server
npm run dev

Open http://localhost:3000. The placeholder page prompts you to run /clone-website.

# Production-like container
docker compose up app --build

# Dev container with bind mount (port 3001 by default)
docker compose up dev --build

# Enable Redis-backed cache
REDIS_ENABLED=true docker compose up app redis --build

Environment variables (see .env.example):

# Health check
curl http://localhost:3000/api/cache/status

# Save clone session metadata
curl -X POST http://localhost:3000/api/cache/sessions \
  -H "Content-Type: application/json" \
  -d '{"session":{"id":"demo","targetUrl":"https://example.com","status":"pending","createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}}'

# Load session
curl "http://localhost:3000/api/cache/sessions?id=demo"

Internal audit notes: docs/internal/AUDIT.md.

Tests live under tests/ and run with Vitest:

npm test           # single run
npm run test:watch # watch mode

Coverage includes:

• Environment configuration parsing
• In-memory cache TTL and CRUD behavior
• Redis store operations (mocked client)
• Clone session helper functions

CI executes the same suite on Node 24 for every pull request.

.
├── src/
│   ├── app/                 # Next.js routes and API handlers
│   │   └── api/cache/       # Cache health + session endpoints
│   ├── components/ui/       # shadcn/ui primitives
│   ├── hooks/               # Shared React hooks (scaffold)
│   ├── lib/
│   │   ├── cache/           # Memory + Redis cache backends
│   │   ├── config/          # Typed environment configuration
│   │   ├── errors/          # Application error types
│   │   └── logger/          # Structured logging utility
│   └── types/               # Shared TypeScript interfaces
├── tests/cache/             # Vitest unit tests
├── scripts/                 # TypeScript build/sync tooling
├── docs/
│   ├── internal/            # Engineering audit notes
│   └── research/            # Agent extraction output (generated)
├── .claude/skills/          # Canonical clone-website skill
├── docker-compose.yml       # app + dev + redis services
├── vitest.config.ts
├── tsconfig.json            # App compiler config
├── tsconfig.scripts.json    # Scripts compiler config
└── tsconfig.test.json       # Test compiler config

Design decisions

• src/lib/cache/ isolates persistence from API routes so agents can reuse cache logic in scripts.
• tests/ is top-level (not colocated) to keep production bundles lean.
• Lockfiles are intentionally gitignored; CI uses npm install.

1. Fork the template and create a feature branch.
2. Run npm install && npm run validate before opening a PR.
3. Keep commits focused; avoid unrelated refactors.
4. Update .env.example when adding configuration keys.
5. Regenerate platform files if you edit AGENTS.md or the clone skill.

Pull requests should include a test plan listing commands run and any manual verification steps.

Do I need Redis?
No. The default in-memory backend works for single-machine agent runs. Enable Redis when multiple agents or CI runners share clone session state.

Can I use this without Claude Code?
Yes. Run npm run sync:skills after editing the canonical skill. Most agents read AGENTS.md or their platform-specific copy automatically.

Will this copy any website automatically?
No. The template provides scaffolding and agent instructions. A coding agent still performs extraction, spec writing, and component generation.

Is scraping always legal?
No. Verify ownership, licensing, and target site terms before cloning. See the ethical use section in AGENTS.md.

Why is package-lock.json ignored?
This template optimizes for fork-level dependency resolution. Generate the lockfile locally with npm install.

MIT — see LICENSE.