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)

4.0 KiB Raw Blame History Unescape Escape