Next-js-Boilerplate AGENTS.md

AGENTS

Principles

• Clarity and consistency over cleverness. Minimal changes. Match existing patterns.
• Keep components/functions short; break down when it improves structure.
• TypeScript everywhere; no any unless isolated and necessary.
• No unnecessary try/catch. Avoid casting; use narrowing.
• Named exports only (no default exports, except Next.js pages).
• Absolute imports via @/ unless same directory.
• Follow existing ESLint setup; don't reformat unrelated code.
• Zod type-only: import type * as z from 'zod';.
• Let compiler infer return types unless annotation adds clarity.
• Options object for 3+ params, optional flags, or ambiguous args.
• Hypothesis-driven debugging: 1-3 causes, validate most likely first.

Token efficiency

• Skip recaps unless the result is ambiguous or you need more input.

Commands

Only these bun run scripts: build-local, lint, check:types, check:deps, check:i18n, test, test:e2e.

Git Commits

Conventional Commits: type: summary without scope. The summary should be a short, specific sentence that explains what changed and where or why, not a vague phrase. Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert. BREAKING CHANGE: footer when needed.

Env

All env vars validated in Env.ts; never read process.env directly.

Styling

Tailwind v4 utility classes. Reuse shared components. Responsive. No unnecessary classes.

React

• No useMemo/useCallback (React compiler handles it). Avoid useEffect.
• Single props param with inline type; access as props.foo (no destructuring).
• Use React.ReactNode, not ReactNode.
• Inline short event handlers; extract only when complex.

Pages

• Default export name ends with Page. Props alias (if reused) ends with PageProps.
• Locale pages: props: { params: Promise<{ locale: string }> } → await props.params → setRequestLocale(locale).
• Escape glob chars in shell commands for Next.js paths.
• Dashboard pages (sit behind auth); define meta once in layout, not in each page.