206 lines
6.4 KiB
Markdown
206 lines
6.4 KiB
Markdown
# Agents Guide (Single Source of Truth)
|
|
|
|
This document is the canonical reference for humans and `Agents` working in this repository. It standardizes stack, structure, workflows, and guardrails so contributions stay consistent and safe.
|
|
|
|
## 1) Scope and goals
|
|
|
|
* Make onboarding fast with a single place to look
|
|
* Define conventions so changes are predictable
|
|
* Provide exact commands that `Agents` can run without guesswork
|
|
* Prevent accidental regressions in routing, theming, SEO, and deployment
|
|
|
|
## 2) Tech stack
|
|
|
|
* **Framework**: Next.js 15.5.4, React 19, TypeScript
|
|
* **Styling**: Tailwind CSS 4, shadcn/ui
|
|
* **Animation**: Framer Motion
|
|
* **Forms**: react-hook-form + Zod
|
|
* **Platform**: Cloudflare Workers via OpenNext
|
|
* **Package manager**: npm
|
|
* **Node**: LTS 20 or 22
|
|
|
|
## 3) Project layout
|
|
|
|
```
|
|
root
|
|
├─ src/
|
|
│ ├─ app/ # App Router pages and layouts
|
|
│ │ ├─ (marketing)/ # Example route groups
|
|
│ │ ├─ api/ # Route handlers
|
|
│ │ └─ layout.tsx # Root layout, see rules below
|
|
│ ├─ components/ # Reusable UI
|
|
│ ├─ data/ # JSON or TS data objects consumed by pages
|
|
│ ├─ lib/ # Utilities, hooks, server actions
|
|
│ ├─ styles/ # globals.css, tailwind utilities if applicable
|
|
│ └─ types/ # Shared types
|
|
├─ public/ # Static assets
|
|
├─ next.config.ts
|
|
├─ tailwind.config.ts
|
|
├─ wrangler.toml # Cloudflare deploy config
|
|
└─ package.json
|
|
```
|
|
|
|
### Import aliases
|
|
|
|
* Prefer absolute imports using `@` mapped to `src` via `tsconfig.json` paths.
|
|
|
|
## 4) Authoritative UI system
|
|
|
|
* **Theme**: dark mode is the default. Do not introduce light-first designs without approval.
|
|
* **Typography**: default to Geist and Geist Mono via CSS variables. If adding a new font, add it as a variable and document it here before use.
|
|
* **Components**: use shadcn/ui primitives. Extend with local wrappers placed in `src/components/ui/`.
|
|
* **Spacing and rhythm**: follow Tailwind 4 defaults. Prefer utility classes over custom CSS unless componentized.
|
|
* **Animation**: keep motion subtle. Framer Motion only for meaningful transitions.
|
|
|
|
## 5) Routing and layout rules
|
|
|
|
* The **root layout** owns global providers, theme class, `<Nav />`, and `<Footer />`. Do not duplicate these in child layouts.
|
|
* Pages live in `src/app`. Keep server components as the default. Promote to client component only when needed.
|
|
* Metadata must be defined per route with the Next.js Metadata API.
|
|
|
|
## 6) SEO and metadata
|
|
|
|
* Use the Metadata API for title, description, Open Graph, and Twitter cards.
|
|
* Add structured data with JSON-LD in the root layout or specific routes when required.
|
|
* All pages must render a unique `title` and `description` suitable for indexing.
|
|
|
|
## 7) Forms and validation
|
|
|
|
* Use `react-hook-form` with Zod schemas.
|
|
* Surface field-level errors and a generic submit error. Never swallow validation errors.
|
|
|
|
## 8) Images and assets
|
|
|
|
* Use Next Image component for remote images.
|
|
* If a new external domain is introduced, add it to `next.config.ts` remote patterns and document it here.
|
|
* Keep `public/` for truly static assets only.
|
|
|
|
## 9) Environment variables
|
|
|
|
Provide a `.env.sample` and keep it in sync. Typical keys:
|
|
|
|
```
|
|
NEXT_PUBLIC_SITE_URL=
|
|
RESEND_API_KEY=
|
|
CF_PAGES_URL=
|
|
```
|
|
|
|
Do not commit real secrets. `Agents` must fail a task rather than hardcode a secret.
|
|
|
|
## 10) Local development
|
|
|
|
```
|
|
# install
|
|
npm ci
|
|
|
|
# run dev server
|
|
npm run dev
|
|
|
|
# type checks and linting
|
|
npm run typecheck
|
|
npm run lint
|
|
|
|
# build and preview
|
|
npm run build
|
|
npm run start
|
|
```
|
|
|
|
Notes
|
|
|
|
* The Next build may be configured to ignore ESLint and TS errors for production bundling speed. CI still gates on `lint` and `typecheck` before merge.
|
|
|
|
## 11) Deployment on Cloudflare Workers with OpenNext
|
|
|
|
### Required wrangler.toml settings
|
|
|
|
```
|
|
name = "site-worker"
|
|
main = ".open-next/worker/index.mjs"
|
|
compatibility_date = "2024-09-23"
|
|
compatibility_flags = ["nodejs_compat"]
|
|
assets = { directory = ".open-next/assets" }
|
|
```
|
|
|
|
### Build and deploy
|
|
|
|
```
|
|
# produce OpenNext build artifacts
|
|
npx open-next@latest build
|
|
|
|
# deploy worker and assets
|
|
npx wrangler deploy .open-next/worker
|
|
```
|
|
|
|
Guidelines
|
|
|
|
* Always run `npm run typecheck` and `npm run lint` before build.
|
|
* Ensure `assets.directory` matches the OpenNext output.
|
|
* Keep the compatibility date at or after 2024-09-23.
|
|
|
|
## 12) Branching, commits, and CI
|
|
|
|
* **Default branch**: `main` is protected.
|
|
* **Workflow**: feature branches -> PR -> required checks -> squash merge.
|
|
* **Commit format**: Conventional Commits. Examples
|
|
|
|
* `feat: add contact form schema`
|
|
* `fix: correct Image remote pattern`
|
|
* `chore: bump dependencies`
|
|
* **Required checks**
|
|
|
|
* `npm run lint`
|
|
* `npm run typecheck`
|
|
* `npm run build` can be optional locally if CI runs it, but must succeed before deploy.
|
|
|
|
## 13) Testing
|
|
|
|
* **Unit**: place tests close to sources, name with `.test.ts` or `.test.tsx`.
|
|
* **E2E**: optional Playwright. If used, add a `playwright.config.ts` and a `npm run e2e` script.
|
|
|
|
## 14) Data and content
|
|
|
|
* Non-secret content belongs in `src/data` as TS modules or JSON. Keep it presentation-agnostic.
|
|
* Do not fetch static project data in client components. Prefer server components or file imports.
|
|
|
|
## 15) `Agents` operating rules
|
|
|
|
1. Read this guide before making changes.
|
|
2. Before adding a dependency, justify it in the PR description and update this document if it affects conventions.
|
|
3. When creating pages, set Metadata and verify unique title and description.
|
|
4. If a build ignores ESLint or TS errors, CI still blocks merges on `lint` and `typecheck`. Fix the errors instead of bypassing checks.
|
|
5. Never commit secrets. Use `.env` and keep `.env.sample` current.
|
|
6. If you change image domains or fonts, document the change here.
|
|
7. Prefer small, reviewable PRs. Include screenshots for UI changes.
|
|
|
|
## 16) Common pitfalls
|
|
|
|
* Adding a remote image domain but forgetting to allow it in `next.config.ts`.
|
|
* Introducing a client component unnecessarily and breaking streaming or SSR.
|
|
* Duplicating navigation inside nested layouts.
|
|
* Styling drift by bypassing Tailwind utilities and shadcn primitives.
|
|
|
|
## 17) Quick command reference
|
|
|
|
```
|
|
# install deps
|
|
npm ci
|
|
|
|
# develop
|
|
npm run dev
|
|
|
|
# quality gates
|
|
npm run lint
|
|
npm run typecheck
|
|
|
|
# build and preview
|
|
npm run build
|
|
npm run start
|
|
|
|
# open-next build and deploy
|
|
npx open-next@latest build
|
|
npx wrangler deploy .open-next/worker
|
|
```
|
|
|
|
|
|
|