AGENTS.md

1# packages/web/ — Marketing Site (Next.js + Cloudflare Workers)
2 
3**Generated:** 2026-05-20
4 
5## OVERVIEW
6 
7Public-facing marketing site for oh-my-opencode / oh-my-openagent. Next.js 15 (App Router) deployed to Cloudflare Workers via [@opennextjs/cloudflare](https://opennext.js.org/cloudflare). Independent of the npm plugin — its own `package.json`, `bun.lock`, and `tsconfig.json`.
8 
9## STACK
10 
11| Layer          | Choice                                                                              |
12| -------------- | ----------------------------------------------------------------------------------- |
13| Framework      | Next.js 15.5 (App Router, RSC)                                                      |
14| Runtime target | Cloudflare Workers (`compatibility_flags: ["nodejs_compat"]`)                       |
15| Adapter        | `@opennextjs/cloudflare` (build → `.open-next/worker.js`)                           |
16| Styling        | Tailwind v4 (`@tailwindcss/postcss`) + shadcn/ui (`components.json`)                |
17| i18n           | `next-intl` with `app/[locale]/...` routing; 4 locales (en/ja/ko/zh) in `messages/` |
18| Animation      | `motion` (Framer Motion v12)                                                        |
19| E2E            | Playwright (`e2e/*.spec.ts`)                                                        |
20| Lint/Format    | ESLint flat config + Prettier (Tailwind plugin)                                     |
21 
22## STRUCTURE
23 
24```
25packages/web/
26├── app/[locale]/         # localized routes (App Router)
27├── components/           # shared UI primitives + shadcn-generated
28├── lib/                  # utility helpers (cn, etc.)
29├── messages/{en,ja,ko,zh}.json  # i18n strings
30├── i18n/                 # next-intl request/routing config
31├── middleware.ts         # next-intl middleware
32├── public/               # static assets (largest dir, ~4 MB)
33├── e2e/                  # Playwright tests
34├── scripts/prepare-build.mjs    # purges .next/cache/fetch-cache before build
35├── next.config.ts
36├── open-next.config.ts
37├── wrangler.toml         # worker name + compatibility settings
38├── playwright.config.ts
39├── eslint.config.mjs
40├── postcss.config.mjs
41├── tsconfig.json
42├── components.json       # shadcn config
43└── package.json
44```
45 
46## SCRIPTS
47 
48```bash
49# from packages/web/ directory
50bun install
51bun run dev              # next dev (local Node.js)
52bun run lint             # biome lint + eslint
53bun run lint:fix
54bun run format           # prettier --write
55bun run format:check
56bun run type-check       # tsgo --noEmit
57bun run build            # next build (Node target — for sanity)
58bun run preview          # opennextjs-cloudflare build + preview locally
59bun run deploy           # opennextjs-cloudflare build + deploy to Cloudflare
60bun run test:e2e         # playwright test
61bun run cf-typegen       # regenerate cloudflare-env.d.ts from wrangler.toml bindings
62```
63 
64## CI/CD
65 
66| Workflow                           | Trigger                                                          | What                                                                    |
67| ---------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
68| `.github/workflows/web-ci.yml`     | push/PR to master/dev that touches `packages/web/**`             | format check, lint, type-check, next build, opennextjs-cloudflare build |
69| `.github/workflows/web-deploy.yml` | push to master that touches `packages/web/**` OR manual dispatch | full deploy via `cloudflare/wrangler-action@v3`                         |
70 
71**Required secrets** (must be configured in repo settings before deploy works):
72 
73- `CLOUDFLARE_API_TOKEN` — token with `Workers Scripts: Edit` permission
74- `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account ID
75 
76A `web-production` GitHub environment is referenced by the deploy workflow so deploys can be gated behind required reviewers / wait timers if desired.
77 
78## RELATIONSHIP TO npm PACKAGE
79 
80The npm package `oh-my-opencode` ships only `dist/`, `bin/`, and `postinstall.mjs` (see root `package.json` `files` field). `packages/web/` is **not** included in any npm publish — it is exclusively a separate Cloudflare deployment target.
81 
82Root `bun test` ignores `packages/web/**` through `bunfig.toml` so `packages/web/e2e/*.spec.ts` does not pollute plugin tests.
83 
84## CONVENTIONS
85 
86- **No path aliases globally** in the omo project, but `packages/web/` is a Next.js app where `@/*` aliases are the framework default. Keep `@/*` confined to packages/web/.
87- Use the existing shadcn primitives in `components/ui/` rather than installing new UI libs.
88- All user-facing copy goes through `messages/{locale}.json`; never hardcode strings in components.
89- Format with prettier before commit — `web-ci.yml` enforces `format:check`.
90 
91## ANTI-PATTERNS
92 
93- Never run `npm install` in `packages/web/`. Use `bun install` only. (Root `.gitignore` already blocks `package-lock.json`.)
94- Never commit `.next/`, `.open-next/`, `.wrangler/`, `node_modules/` (covered by `packages/web/.gitignore`).
95- Never deploy locally with `bun run deploy` against production — use the GitHub Actions workflow so Cloudflare credentials live in one place.
96