diff --git a/AGENTS.md b/AGENTS.md index 1a98167..930a84d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,6 +121,12 @@ configured and difficult to re-stabilize. ### Always do these: +- **ALWAYS update `AGENTS.md` when your work changes anything documented here** — + architecture, file paths, new files, Payload config, known issues, workflows. Do + this in the same task, not as a follow-up. The intro says this too but it bears + repeating as a hard rule: the next agent reads this file first and will be misled + by stale information. + - **ALWAYS use `bun typecheck` to validate your work**, never `bun build`. Typecheck is fast and sufficient. Build is slow and for production deployments only. @@ -531,9 +537,11 @@ packages/backend/ │ ├── auth.ts # Auth setup + all user-related functions │ ├── crons.ts # Cron jobs (commented examples) │ ├── files.ts # File upload/storage +│ ├── globals.d.ts # Types process.env for Convex backend env vars │ ├── http.ts # HTTP routes (auth only) — DO NOT TOUCH │ ├── schema.ts # Database schema — the source of truth │ └── tsconfig.json # Convex-required TS config +├── eslint.config.ts # ESLint config for the backend package ├── scripts/ │ └── generateKeys.mjs # RS256 JWT keypair generator for Convex Auth └── types/ @@ -547,6 +555,19 @@ structure. When `bun typecheck` runs from the repo root, it will print TypeScrip output for `@gib/backend` (because there's no valid project to check). This is expected and not an error. +**Note on `globals.d.ts`:** The Convex runtime supports `process.env` for reading +environment variables set in the Convex Dashboard. Because the Convex tsconfig does +not include `@types/node`, `process` would otherwise be untyped. `globals.d.ts` +declares `process.env` with the specific variables this backend uses. If you add a +new env var to the Convex backend, add it here too so TypeScript and ESLint are happy. + +**Note on `convex/utils.ts`:** This file may be regenerated by `convex dev` as a +Convex CLI utility scaffold. It contains `missingEnvVariableUrl` / `deploymentName` +helpers that reference `CONVEX_CLOUD_URL` — a Convex Cloud concept irrelevant to this +self-hosted setup. If the file reappears, you can safely delete it (nothing in the +codebase imports it) or leave it — it won't affect runtime behaviour since the +functions are never called. + ### Schema design — always extend `users` directly The preferred and enforced approach in this repo is to **extend the `users` table @@ -825,6 +846,14 @@ Current state of the template: content is partial or missing fields - live preview works by loading `/` with `?preview=true` and rendering `RefreshRouteOnSave` +- `payload.config.ts` sets `serverURL: env.NEXT_PUBLIC_SITE_URL` — required for + Payload to construct absolute URLs in the admin UI and live preview +- `get-landing-page-content.ts` only calls `noStore()` when `isPreview` is true — + normal (non-preview) requests are cacheable by Next.js. Do not add `noStore()` + back unconditionally. +- `apps/next/src/app/(frontend)/page.tsx` wraps the Payload fetch in a try/catch and + falls back to `defaultLandingPageContent` if Postgres is unreachable — the landing + page always renders even when the CMS is down If you need a deeper walkthrough, read `docs/payload-cms.md`. That file should stay in sync with the actual Payload implementation in this repo. diff --git a/apps/next/payload-types.ts b/apps/next/payload-types.ts index 6ef2b32..75421f4 100644 --- a/apps/next/payload-types.ts +++ b/apps/next/payload-types.ts @@ -77,15 +77,9 @@ export interface Config { collectionsSelect: { users: UsersSelect | UsersSelect; 'payload-kv': PayloadKvSelect | PayloadKvSelect; - 'payload-locked-documents': - | PayloadLockedDocumentsSelect - | PayloadLockedDocumentsSelect; - 'payload-preferences': - | PayloadPreferencesSelect - | PayloadPreferencesSelect; - 'payload-migrations': - | PayloadMigrationsSelect - | PayloadMigrationsSelect; + 'payload-locked-documents': PayloadLockedDocumentsSelect | PayloadLockedDocumentsSelect; + 'payload-preferences': PayloadPreferencesSelect | PayloadPreferencesSelect; + 'payload-migrations': PayloadMigrationsSelect | PayloadMigrationsSelect; }; db: { defaultIDType: number; @@ -639,6 +633,7 @@ export interface Auth { [k: string]: unknown; } + declare module 'payload' { export interface GeneratedTypes extends Config {} -} +} \ No newline at end of file diff --git a/apps/next/src/app/(payload)/admin/importMap.js b/apps/next/src/app/(payload)/admin/importMap.js index dddb9e7..eb1ae47 100644 --- a/apps/next/src/app/(payload)/admin/importMap.js +++ b/apps/next/src/app/(payload)/admin/importMap.js @@ -1,6 +1,5 @@ -import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'; +import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc' export const importMap = { - '@payloadcms/next/rsc#CollectionCards': - CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1, -}; + "@payloadcms/next/rsc#CollectionCards": CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 +} diff --git a/packages/backend/convex/globals.d.ts b/packages/backend/convex/globals.d.ts index cca01ea..f6a3c33 100644 --- a/packages/backend/convex/globals.d.ts +++ b/packages/backend/convex/globals.d.ts @@ -5,7 +5,6 @@ declare const process: { readonly USESEND_API_KEY?: string; readonly USESEND_URL?: string; readonly USESEND_FROM_EMAIL?: string; - readonly CONVEX_CLOUD_URL?: string; readonly [key: string]: string | undefined; }; }; diff --git a/turbo.json b/turbo.json index 5562359..38d1a91 100644 --- a/turbo.json +++ b/turbo.json @@ -16,7 +16,6 @@ "CONVEX_SELF_HOSTED_URL", "CONVEX_SELF_HOSTED_ADMIN_KEY", "CONVEX_SITE_URL", - "CONVEX_CLOUD_URL", "USESEND_API_KEY", "USESEND_URL", "USESEND_FROM_EMAIL",