Skip to content

CLAUDE.md

Latest commit

 

History

History
57 lines (36 loc) · 4.04 KB

CLAUDE.md

File metadata and controls

57 lines (36 loc) · 4.04 KB
Raw

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/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@AGENTS.md @design/DESIGN-SYSTEM.md

What this project is

frontend-pendev is the front-end for a YouTube-style video platform (channel pages, video listings/players, browse/watch flows). As of now the repo is still the create-next-app scaffold — app/page.tsx is the untouched starter page — so almost everything is greenfield: when adding a feature, you are establishing the convention, not following one.

Commands

npm run dev      # Turbopack dev server on :3000 (also rewrites the AGENTS.md rules block)
npm run build    # production build
npm run start    # serve the production build
npm run lint     # eslint (flat config); `next lint` was removed in Next 16

No test runner is installed yet. If you add one, prefer the setup described in node_modules/next/dist/docs/01-app/02-guides/testing/.

Stack

  • Next.js 16.3.2 (App Router, Turbopack by default) + React 19.2
  • TypeScript strict, @/* → repo root
  • Tailwind CSS v4 via @tailwindcss/postcss — no tailwind.config.*; theme tokens are declared in app/globals.css under @theme inline, and dark mode is driven by prefers-color-scheme, not a dark class. Design tokens come from design/pendev/youtube-channel.pen — never invent one and never hardcode a color; see design/DESIGN-SYSTEM.md for the translation rules.
  • Geist Sans/Mono loaded in app/layout.tsx and exposed as --font-geist-sans / --font-geist-mono

Next.js 16 gotchas that bite

Your training data likely predates this version. Read node_modules/next/dist/docs/ before writing framework code; the most common traps:

  • Request APIs are async. params, searchParams, cookies(), headers(), draftMode() all return Promises — await them.
  • Typed route props are global. app/layout.tsx uses LayoutProps<"/">; pages use PageProps<"/route">. These are generated into .next/types — don't hand-roll prop types, and expect them to be missing until next dev/next build has run once.
  • middleware.ts is now proxy.ts.
  • next/image changed defaults (minimumCacheTTL, imageSizes, qualities) and restricts local-IP sources; next/legacy/image and images.domains are gone.
  • Parallel routes now require default.js.

Agent tooling

.mcp.json wires up playwright and chrome-devtools (drive/inspect the running app in a browser) and pencil (read/generate .pen design files). A .pen is plain JSON with stable ids. Read values with jq; query the tree or render nodes with pen interactive --in <abs path> --out <tmp>, which runs headless and needs no editor (requires pen CLI >= 0.3.5 — 0.3.2 loads a .pen with relative image fills as an empty document, silently). Edit only through the MCP tools or the CLI's save(); hand-editing the JSON breaks tree consistency. design/pendev/ is the home for those design sources; see design/DESIGN-SYSTEM.md before inventing a layout.

Consider adding next-devtools-mcp to .mcp.json if you need build/runtime/type errors from the live dev server (see node_modules/next/dist/docs/01-app/02-guides/mcp.md).

Conventions

  • AGENTS.md is regenerated by next dev. If it shows up dirty in a diff, commit it with your work rather than reverting it.
  • .history/ is VS Code Local History; it is untracked and should stay out of commits.