Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (65 loc) · 4.11 KB

CLAUDE.md

File metadata and controls

87 lines (65 loc) · 4.11 KB
Raw

CLAUDE.md

Guidance for Claude when working in this repo (JSConf Brasil landing page).

What this is

Three pieces, one repo:

  • Website — Docusaurus 3 + React 19, static, deployed to GitHub Pages (jsconf.com.br). Source in src/website/. File-based routes under src/website/pages/. i18n in i18n/ (pt-BR default, en-US, es-419) via Docusaurus <Translate> / code.json.
  • Server — a single Cloudflare Worker (src/server/index.ts), custom domain api.jsconf.com.br. No framework: a fetch handler with a manual switch router. Helpers, routes, repositories, configs split under src/server/.
  • Database — Cloudflare D1 (SQLite), bound as DB. Schema in resources/schema.sql (idempotent CREATE TABLE IF NOT EXISTS). Apply with npm run db:init (local) / db:init:remote.

Deploy: push to main → .github/workflows/cd_deploy.yml builds both, deploys the worker via wrangler and the site to the website branch.

Commands

npm start            # site (pt-BR) + worker via wrangler dev, concurrently
npm run server       # worker only (wrangler dev)
npm run db:init      # apply resources/schema.sql to local D1
npm test             # poku (-r=compact)
npm run typecheck    # tsc
npm run lint         # prettier --check  (lint:fix to write)
npm run build        # worker + docusaurus
npm run images       # regenerate the responsive image variants (commit the output)

Run npm ci first if node_modules is missing (typecheck/test need deps).

Images: every photo the shared Image wrapper renders ships as a srcset ladder (200/400/800 + the file's own width, WebP). The variants are generated by tools/generate-image-variants.ts and committed — no build hook — so run npm run images after adding or replacing anything under the paths listed at the top of that script. src/website/configs/images.ts holds the naming/width rules that the script and the wrapper both read; changing one without the other means 404s.

Conventions

  • Style: no else (early-return + guard clauses), avoid let, prefer for..of over .forEach, keep it simple over clever. TS: switch default x satisfies never, Record<Enum, T>.
  • Server shape: routes in src/server/routes/, registered in routes.ts + the index.ts switch (METHOD /path). DB access in repositories/, validated with zod. Responses via helpers/response.ts. Reuse the existing helpers (request.ts, session.ts, etc.).
  • Validation is the trust boundary server-side; the frontend schemas are UX only.
  • Tests: poku, files *.test.ts under test/ mirroring src/. Mock D1 with a plain object implementing prepare().bind().run()/all() (see test/server/routes/c4p/__utils__.ts and test/server/routes/vote.test.ts).
  • Secrets: wrangler secret put (see npm run secret); never commit them. .env.example lists what exists.

Git / PRs

  • Conventional commits, single -m, no Claude attribution. Never push to main — branch first. No gitmoji.
  • git here needs a clean env to avoid shell-hook hangs: env -i HOME=$HOME PATH=/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin /usr/bin/git --no-pager …

In-flight work

The voting-system branch adds attendee voting on C4P talks (guild.host OAuth identity, manager-token-based ticket-tier lookup, D1-backed vote casting with budget limits) and is built and verified end-to-end against a real guild.host login. See DEVELOPMENT.md for the technical deep-dive (architecture, OAuth flow, DB schema) and TODO.md for the remaining deploy steps and known caveats.

Headroom Learned Patterns

Auto-generated by headroom learn on 2026-06-26 — do not edit manually

Dependencies

~1,500 tokens/session saved

  • Server session/JWT uses jose (^6.x). The cookie package was tried and removed — it is NOT a dependency; don't re-add it.
  • To check an installed package version, grep -E '"version"' node_modules/<pkg>/package.json. Do NOT use node -e "require('<pkg>/package.json')" — packages like jose define exports and throw ERR_PACKAGE_PATH_NOT_EXPORTED.