convex-monorepo/AGENTS.md

AGENTS.md

Architecture

• apps/next: Next.js 16 frontend.
• apps/expo: Expo scaffold; only work here when explicitly requested.
• packages/backend/convex: self-hosted Convex functions, schema, and auth.
• packages/ui: shared shadcn-based UI components.
• tools: shared ESLint, Prettier, Tailwind, TypeScript, and Vitest config.
• Local development uses host-run apps, local Convex on ports 3250/3251, and its own data volume. Convex does not use Postgres unless a cloned project explicitly enables the commented optional POSTGRES_URL example.

Protected and generated files

• Never edit packages/backend/convex/_generated/** or packages/backend/convex/http.ts.
• Do not rename apps/next/next.config.js or apps/next/src/proxy.ts.
• Preserve typescript.ignoreBuildErrors in Next config.
• Do not modify Sentry config or tools/tailwind/theme.css unless requested.
• Generated .cache, .turbo, .local, and environment files are ignored.

Environment rules

• Local dev and staging come only from Infisical via scripts/with-env; it never falls back to .env*.
• Run infisical login and infisical init before local development.
• Machine-generated values belong in .local/<env>.generated.env; never put the generated Convex admin key in shared Infisical.
• CI reads staging through scripts/ci-export-env.mjs, logged in as the read-only convexmonorepo-base-ci machine identity (Gitea secrets INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET). scripts/export-env refuses to run in CI.
• This template's staging has no Convex admin key, so nothing here can deploy to a real backend. A cloned app gets its own Infisical project.
• If you are logged in to more than one Infisical account, put INFISICAL_EMAIL=... in scripts/flags/infisical.env (gitignored) and the scripts switch the CLI to that account before exporting.
• Server code imports validated variables from @/env. Client components and instrumentation-client.ts import from @/publicEnv, which keeps zod out of the browser bundle. Never read process.env elsewhere.
• Add cache-relevant variables to turbo.json globalEnv.

Code and dependency rules

• Use const arrow functions instead of function declarations.
• Add .js extensions to Convex generated-file imports.
• Put custom frontend routes directly in apps/next/src/app or normal route groups such as apps/next/src/app/(auth).
• Extend the Convex users table for application user data; do not add a profile table by default. Authenticate protected functions.
• Manage shared versions in root catalogs. Never run bun update in a package.
• Run root bun install and verify with bun lint:ws.
• Update this guide when architecture or workflows change.

Local stack

bun db:up          # start Convex and dashboard
bun dev:next       # host Next + deploy/watch local Convex functions
bun db:down        # stop and preserve Convex data
bun db:down:wipe   # remove Convex volume and generated admin key
bun db:sync-env    # re-push Infisical dev values into the local Convex env
bun dev:kill       # stop dev servers that survived a Ctrl-C

Local URLs: app http://localhost:3000, Convex http://localhost:3250, dashboard http://localhost:6795. The Compose project and containers are named convexmonorepo-base-local* so this stack can run beside the Payload template's. Use INFISICAL_ENV=staging bun dev:next for staging services. Normal db:up never connects to staging and does not start Postgres.

Analytics and bundle size

• Plausible (NEXT_PUBLIC_PLAUSIBLE_SRC, the per-site script URL) loads through a same-origin proxy under /pa. PostHog (NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST) loads after the page is idle through /ingest. Both stay off when their env is unset.
• Session replay comes from PostHog. Sentry carries errors and traces only.
• packages/ui/src/index.tsx holds re-exports only (cn and ccn live in utils.ts). With optimizePackageImports in next.config.js, each page loads only the UI modules it imports. Declaring anything in the index breaks that.

Validation

Use bun typecheck, never a production build for routine validation. The full gate is SKIP_E2E=1 bun run ci:check; local-stack smoke e2e is bun test:e2e. Pre-commit runs lint-staged serially and pre-push runs the bounded full gate.