56 lines
4.0 KiB
Markdown
56 lines
4.0 KiB
Markdown
# AGENTS.md
|
||
|
||
This file provides guidance to Opencode when working with code in this repository.
|
||
|
||
## Repository Snapshot
|
||
|
||
TypeScript + React 19 (Next.js 15.5.4) site builder for Biohazard VFX studio. Single npm workspace. Deployed to Cloudflare Workers via OpenNext. ESLint + TypeScript strict mode enforced pre-commit. No automated tests; manual QA in Chromium/Safari only. (Sources: package.json, tsconfig.json, README.md)
|
||
|
||
## Commands
|
||
|
||
| Task | Command | Scope | Source |
|
||
|------|---------|-------|--------|
|
||
| Dev server | `npm run dev` | Root | package.json:6 |
|
||
| Build (Next.js) | `npm run build` | Root | package.json:7 |
|
||
| Build (Cloudflare Workers) | `npm run build:open-next` | Root | package.json:8 |
|
||
| Lint (ESLint) | `npm run lint` | Root | package.json:10 |
|
||
| Type check (TypeScript) | `npm run type-check` | Root | package.json:11 |
|
||
| Start production server | `npm run start` | Root | package.json:9 |
|
||
|
||
**Run a single test:** Not applicable; no automated test runner configured.
|
||
|
||
## Architecture Overview
|
||
|
||
- **Entry point**: `src/app/layout.tsx` (root layout with Navigation & Footer); app routes in `src/app/{route}/page.tsx` (about, contact, portfolio, services). (Source: README.md:61–69, src/app/layout.tsx)
|
||
- **Components**: Functional React + Radix UI via shadcn/ui. Primitives in `src/components/ui/`; feature components in `src/components/`. (Source: README.md:70–79, package.json:16–24)
|
||
- **Data & utils**: Project and service metadata in `src/data/projects.ts` and `src/data/services.ts`; shared utilities in `src/lib/utils.ts`. (Source: README.md:80–84)
|
||
- **Styling**: Tailwind CSS 4 + CSS variables in `src/app/globals.css`; components use `clsx` + `tailwind-merge` for conditional styles. (Source: tsconfig.json, package.json:39)
|
||
- **Forms**: `react-hook-form` + Zod validation; e.g., MultiStepForm (contact page). (Source: package.json:14–15, 33, 35)
|
||
- **External services**: Instagram Feed component integrates Instagram API via `src/lib/instagram-api.ts`. Remote images from unsplash.com. (Source: next.config.ts:7–13, src/lib/)
|
||
- **Deployment**: OpenNext adapter for Cloudflare Workers. Build output in `.open-next/` (worker.js + assets). Domain routes in wrangler.toml. (Source: wrangler.toml, open-next.config.ts, next.config.ts:16–22)
|
||
|
||
## Conventions and Rules
|
||
|
||
From CONTRIBUTING.md:
|
||
|
||
- **Commit format**: conventional commits (`feat(scope): subject`). Atomic commits. Examples: `feat(portfolio): add project filtering`, `fix(header): resolve mobile menu overflow`. (CONTRIBUTING.md:122–147)
|
||
- **Branch strategy**: `main` (production), `develop` (integration), `feature/*`, `fix/*`, `hotfix/*`. Always create from `develop`. (CONTRIBUTING.md:49–54, 57–62)
|
||
- **React/Next.js**: Server components by default; client-only where needed. Single responsibility per component. Keep custom CSS minimal. (CONTRIBUTING.md:80–92)
|
||
- **TypeScript**: Avoid `any`. Define interfaces for props and API responses. (CONTRIBUTING.md:74–78)
|
||
|
||
## CI Hooks That Matter Locally
|
||
|
||
From `.gitea/workflows/ci.yml`:
|
||
|
||
- **Lint & type-check** (lines 14–35): `npm run lint` and `npm run type-check` run on every PR to main/develop. **Failures block merge.**
|
||
- **Build** (lines 37–65): `npm run build` with `NODE_ENV=production` required before merge. Artifacts uploaded for 7 days.
|
||
|
||
Run both before pushing: `npm run lint && npm run type-check && npm run build`.
|
||
|
||
## Known Pitfalls
|
||
|
||
- **Build ignores errors**: next.config.ts (lines 17–22) sets `eslint.ignoreDuringBuilds` and `typescript.ignoreBuildErrors` to `true`. Lint and typecheck **must pass locally** before deploy or CI will catch them. (Source: next.config.ts)
|
||
- **No test suite**: Manual QA only. Verify changes in Chromium and Safari before PR. (Source: README.md:55, AGENTS.md (this file, earlier))
|
||
- **Secrets in wrangler.toml**: Never commit credentials there. Use Gitea Secrets for env vars. (Source: CONTRIBUTING.md:153, AGENTS.md (this file, earlier))
|
||
- **Cloudflare compatibility**: Requires `nodejs_compat` flag and compatibility date ≥ 2024-09-23. (Source: wrangler.toml:4)
|