AGENTS.md · diff
git:20260214.65364f3 to git:20260502.8c00a56
28 added, 203 removed. Audit A to A.
- # AGENTS.md - Developer Guidelines
-
- This document provides guidelines for agents working on this codebase.
-
- ## Project Overview
-
- This is a Next.js + Payload CMS portfolio website with PostgreSQL. It uses:
-
- - Next.js 16 (App Router)
- - Payload CMS 3.0
- - Tailwind CSS 4
- - TypeScript (strict mode)
- - Motion (Framer Motion)
- - Better Auth
-
- ---
+ # AGENTS.md
## Commands
- ### Development
-
```bash
- pnpm dev # Start dev server
- pnpm devsafe # Clean restart (removes .next cache)
- pnpm start # Production server
- ```
-
- ### Building
-
- ```bash
- pnpm build # Next.js production build
- ```
-
- ### Linting & Formatting
-
- ```bash
- pnpm lint # ESLint
- pnpm format # Prettier (write mode)
- ```
-
- ### Testing
-
- ```bash
- pnpm vitest run # Run all unit tests
- pnpm vitest run <file> # Run single test file
- pnpm vitest --watch # Watch mode
- ```
-
- Note: Playwright is installed but not configured. No E2E tests currently exist.
-
- ### Payload CMS
-
- ```bash
- pnpm payload generate:types # Generate TypeScript types
- pnpm payload generate:importmap
- ```
-
- ---
-
- ## Code Style
-
- ### Formatting (Prettier)
-
- - Single quotes
- - Trailing commas: all
- - Print width: 100
- - Semicolons: yes
-
- ### TypeScript
-
- - Strict mode enabled
- - Use explicit types for function parameters and return types
- - Use `type` for unions/interfaces, `interface` for object shapes
-
- ### Imports
-
- - Use `@/` path alias (configured in tsconfig.json)
- - Group imports: external → internal → relative
- - Use `import { x } from 'module'` (named imports preferred)
-
- ```typescript
- // Good
- import { useState } from 'react';
- import { cn } from '@/lib/cn';
- import { Button } from '@/components/ui/button';
- import type { ButtonProps } from '@/components/ui/button';
- ```
-
- ### Components
-
- #### Client Components
-
- Add `'use client'` at the very top of the file.
-
- ```typescript
- 'use client';
-
- import { useState } from 'react';
- ```
-
- #### Using forwardRef
-
- Use `forwardRef` for components that need to accept refs:
-
- ```typescript
- const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
- ({ className, ...props }, ref) => {
- return <div ref={ref} className={className} {...props} />;
- },
- );
- MyComponent.displayName = 'MyComponent';
- ```
-
- #### Component Variants
-
- Use `cva` (class-variance-authority) for variant components:
-
- ```typescript
- import { cva, type VariantProps } from 'class-variance-authority';
-
- const buttonVariants = cva('base classes', {
- variants: {
- variant: { default: '...', destructive: '...' },
- size: { default: '...', sm: '...' },
- },
- defaultVariants: { variant: 'default', size: 'default' },
- });
-
- type ButtonProps = VariantProps<typeof buttonVariants> & { ... };
- ```
-
- ### Styling
-
- - Use Tailwind CSS for all styling
- - Use `cn()` utility from `@/lib/cn` for class merging
- - Use design tokens (colors, spacing) from Tailwind
-
- ```typescript
- import { cn } from '@/lib/cn';
-
- <div className={cn('base classes', condition && 'conditional-class', className)} />
- ```
-
- ### Error Handling
-
- - Use try/catch with async operations
- - Return proper error types
- - Never expose secrets in error messages
-
- ### Naming Conventions
-
- - Components: PascalCase (`Button`, `HeaderActions`)
- - Hooks: camelCase with `use` prefix (`useMounted`, `useTheme`)
- - Utilities: camelCase (`formatDate`, `cn`)
- - Files: kebab-case (`theme-toggle.tsx`, `auth-client.ts`)
-
- ### Exports
-
- - Use named exports for components and utilities
- - Export types separately when needed
-
- ```typescript
- export { Button, buttonVariants };
- export type { ButtonProps };
- ```
-
- ---
-
- ## Project Structure
-
- ```
- src/
- ├── app/ # Next.js App Router pages
- │ ├── [locale]/ # Internationalized routes
- │ ├── (payload)/ # Payload admin routes
- │ └── api/ # API routes
- ├── components/ # React components
- │ └── ui/ # Reusable UI components
- ├── collections/ # Payload CMS collections
- ├── features/ # Feature-specific code
- ├── hooks/ # Custom React hooks
- ├── lib/ # Utilities and helpers
- ├── locales/ # i18n translation files
- └── payload.config.ts # Payload CMS configuration
+ pnpm dev # Start dev server (http://localhost:3000)
+ pnpm build # Production build
+ pnpm lint # ESLint
+ pnpm format # Prettier write
+ pnpm payload generate:types # Regenerate Payload CMS types
+ pnpm devsafe # Clean .next and restart dev
```
- ---
-
- ## Path Aliases
-
- - `@/*` → `src/*`
- - `@payload-config` → `src/payload.config.ts`
-
- ---
-
- ## Common Patterns
+ Note: All node commands require `NODE_OPTIONS=--no-deprecation` (set automatically in scripts).
- ### Server vs Client Components
+ ## Architecture
- - Default to server components
- - Add `'use client'` only when needed (hooks, event handlers, browser APIs)
+ - **Locale routing**: `[locale]/` route segment — all public pages under `src/app/[locale]/(main)/`
+ - **Payload admin**: `/admin` via `(payload)` route group
+ - **Collections**: `src/collections/*.ts` — maps to PostgreSQL tables
+ - **Components**: `src/components/ui/` for primitives, `src/components/` for domain components
+ - **Features**: `src/features/` for feature-specific logic
- ### Internationalization
+ ## Tech Stack
- - Use `next-intl` for i18n
- - Routes under `[locale]` directory
- - Translation files in `src/locales/`
+ - Next.js 16 (App Router), React 19, Tailwind CSS 4
+ - Payload CMS 3.0 + Vercel Postgres adapter
+ - i18n via next-intl (`src/i18n/`)
+ - Strict TypeScript (`strict: true` in tsconfig)
- ### Database
+ ## Dev Notes
- - Use `@neondatabase/serverless` for PostgreSQL
- - Database client: `src/lib/db.ts`
+ - Requires `.env` with `POSTGRES_URL`, `PAYLOAD_SECRET`, `GROQ_API_KEY`
+ - Use `@payload-config` import alias for config file
+ - Use `@/*` alias for `src/*`
+ - Migrations in `src/migrations/`
- ### Authentication
+ ## Git/Workflow
- - Use Better Auth with GitHub OAuth
- - Auth utilities: `src/lib/auth.ts` (server), `src/lib/auth-client.ts` (client)
+ - Husky pre-commit hooks active
+ - commitlint uses Conventional Commits format
+ - lint-staged runs ESLint fix + Prettier write on staged files