# Repository Guidelines ## Project Overview **CedarJS** is an opinionated, full-stack React framework (frontend: React, API: GraphQL, database: Prisma) forked from [RedwoodJS](https://github.com/redwoodjs/redwood). Active maintenance, experimental ESM support, recurring jobs, and modern Node support (Node 24+). Before proposing a design for a new feature, read [`docs/design-principles.md`](docs/design-principles.md) — it captures cross-cutting design principles (e.g. ambient context with fail-closed defaults) that new features should be measured against. ## Project Structure & Module Organization - Monorepo managed with Nx + Yarn workspaces. - Source packages live under `packages/` (framework packages, adapters, auth providers, CLI packages, mailer, templates). - Shared tooling and scripts live in `tasks/` and `upgrade-scripts/`. - Test fixtures live in `__fixtures__/` - Cedar test apps for local testing live in `local-testing-project` and `local-testing-project-live` - Docs and reference material are in `docs/` and top-level `README.md`. ## Build, Test, and Development Commands - `yarn install`: install dependencies (Yarn v4 as pinned in `package.json`). Do not use npm. - `yarn build`: build all packages via Nx. - `yarn build:clean`: remove prior build output, then rebuild. - `yarn lint` / `yarn lint:fix`: run ESLint across packages (or auto-fix). - `yarn format` / `yarn format:check`: run Prettier write/check. - `yarn test`: run package tests via Nx. Use `CI=1` for non-interactive mode. - `yarn test:types`: run type-level tests. - `yarn e2e`: create a fresh app and run the Playwright tutorial test against it (`tasks/e2e/`). To run commands on a single package: ```bash yarn workspace @cedarjs/cli build yarn workspace @cedarjs/internal test ``` ## Development Workflow To test framework changes against a real Cedar project: 1. **Sync method (recommended):** navigate to your target Cedar project and run `CFW_PATH=/path/to/cedar yarn cfw project:sync` — builds the framework, copies dependencies, watches for changes. 2. **CLI dev method:** useful for testing CLI changes without a full sync: `cd packages/cli && yarn dev --cwd /path/to/target/project` 3. **Test project generation:** create a fresh test project with current framework code: `yarn build:test-project ` Use `yarn dedupe` to manage duplicate packages. Keep `package.json` files sorted (`yarn check`). ## Coding Style & Naming Conventions - Formatting is enforced by Prettier (`tabWidth: 2`, `singleQuote: true`, `semi: false`, `trailingComma: all`). - ESLint config is in `eslint.config.mjs` and is expected to pass on CI. - Prefer consistent package naming and scopes: `packages//`. - Keep file and symbol names aligned with existing package conventions. - Place comments on a separate line immediately above the affected code using `//`. For documenting function/variable usage, use JSDoc. Avoid inline or end-of-line comments. - Avoid introducing new dependencies unless necessary. - Always put type imports on a separate `import type { ... }` line. Never combine type and value imports in a single `import` statement (e.g., avoid `import { foo, type Bar } from '...'`; instead write `import { foo } from '...'` and `import type { Bar } from '...'` on separate lines). ### Writing Comments, PR Descriptions, and Changelogs Write for readers who see only the **current** state of the code and have no historical context. Do not write prose that references earlier versions, past behavior, or the evolution of the code. The reader should never need to know what the code _used_ to do to understand what it does now. - **Describe the present, not the history.** Comment on what the current code does and why. Never say "don't do X anymore", "no longer", "previously", "this was once Y", "we used to", or "instead of the old approach". These require the reader to reconstruct a timeline they don't have. - **Write the removed-information directly.** If a comment explains why a behavior was _removed_ or why a particular approach is _not_ used, state the current reason plainly. For example, prefer "This path is not supported" over "we removed support for this path". Prefer "X is not done here" over "X used to be done here, but not anymore". - **Comments in code, PR descriptions, release notes, and changelog entries are all self-contained.** The same rule applies everywhere prose is written. Description text should read correctly if read in isolation, months or years later. - **If a decision's reasoning matters, frame it in terms of the current trade-off**, not the decision history: "We use Y because X is unreliable" rather than "We switched from X to Y". ## Type Safety & Casting - Prefer precise types and type guards over casts whenever possible. - Use `unknown` for values from untyped/external boundaries (catch variables, dynamic module imports, process/env payloads) and narrow before use. - Use type assertions (`as`) only as a last resort after narrowing or introducing a local type alias/interface is not practical. - Avoid `as any`. If `any` is truly unavoidable, add a short inline comment that explains why and what boundary/limitation requires it. - Every non-obvious cast must include a short comment describing why it is safe or necessary. - Avoid chained assertions unless required (e.g. `as unknown as X` at library typing boundaries); document why when used. - When filtering arrays, prefer typed predicates (e.g. `(v): v is T => Boolean(v)`) instead of broad casts like `as T[]`. - **Never use `@ts-ignore`.** Always prefer `@ts-expect-error` with a clear explanation of why it's needed. - **Never use `e as Error` in try/catch clauses.** The caught value is `unknown` and may not be an `Error`. Always narrow the type properly, e.g.: ```ts } catch (e) { const message = e instanceof Error ? e.message : String(e) } ``` ## Testing Guidelines - Unit/integration tests are executed through `yarn test` (Nx targets). When running `vitest` directly, use `--run` to disable watch mode. - Type tests use `yarn test:types`. - E2E: Playwright. - When adding tests, follow local package naming patterns and keep tests colocated with the package. - For larger changes, run `yarn build && yarn build:pack` to generate package tarballs, then run `yarn install` inside `local-testing-project` to verify your changes inside an actual Cedar application. ## Commit & Pull Request Guidelines - Commit history follows Conventional Commits with scopes, e.g. `feat(realtime): ...`, `fix(cli): ...`, `chore(deps): ...`. - PRs should include a clear summary, testing notes (commands run), and linked issues when applicable. - Add screenshots or CLI output when changes affect user-facing behavior. - Use `gh api repos/cedarjs/cedar/pulls//comments --jq '.[] | {user: .user.login, path: .path, line: .line, body: .body}'` to get review comments for a PR. If you don't already know the PR number you can run `gh pr view --json number --jq .number` to get it ## Agent-Specific Notes - Prefer `rg` for searching and keep changes focused to the relevant package(s). - Avoid touching unrelated files unless required by the change. ## E2E Netlify Deploy Test - Test files in `tasks/netlify-tests/`: - `vitest.config.mts` — vitest runner config (setupFiles, include patterns) - `vitest.setup.mts` — validates `NETLIFY_DEPLOY_URL` env var, sets `process.env.DEPLOY_URL` - `netlify.test.mts` — tests API `handleRequest`, legacy handlers, and web SPA shell against deployed Netlify URL - `skew-protection.test.mts` — tests skew protection across two deploys: the cookie is only set on HTML, old assets and API routes are served by the old deploy for its token (cookie, header, query), page loads always get the latest deploy - CI workflow in `.github/workflows/e2e-netlify.yml`: - Uses `__fixtures__/test-project/` as the test project (ESM, needed by Netlify vite plugin) - Runs tarsync to link local packages - Removes SQLite migrations (`rm -rf api/db/migrations`), then runs `yarn cedar setup neon` to provision a fresh Neon Postgres database and create Postgres baseline migration - Links site with `netlify link --id "$SITE_ID" --filter web` - Runs `yarn cedar setup deploy universal-deploy`, then `yarn cedar setup deploy netlify --ud` - Sets `DATABASE_URL` and `DIRECT_DATABASE_URL` on the Netlify site via `netlify env:set --filter web` for runtime access - Deploys via `npx netlify deploy --filter web --prod --json` (no `--no-build`), which runs the `netlify.toml` build command (`yarn cedar build --ud --apiRootPath=/.api/functions && yarn cedar prisma migrate deploy && yarn cedar data-migrate up`). Netlify only sets `NETLIFY_SKEW_PROTECTION_TOKEN` for builds it runs, so this is required for skew protection - Records the first deploy's `AboutPage-*.js` and `index-*.js` assets and `cedar-skew-token` cookie, runs `netlify.test.mts`, then changes `AboutPage` and the `hello` greeting (`api/src/lib/greeting.ts`), deploys again, and runs `skew-protection.test.mts` (skipped unless `NETLIFY_SKEW_PROTECTION_E2E=1`) - All test-project commands use `working-directory: ../cedar-test-app` (not `CEDAR_CWD`) - CI orchestration in `.github/workflows/ci.yml` — `e2e-netlify` job calls the workflow, runs only on `cedarjs/cedar` repo - API function URLs on Netlify use `/.api/functions/` (configured via `apiRootPath`; routed through the `server` function from `@netlify/vite-plugin` which has `path: "/*"`) - Fixture functions in `__fixtures__/test-project/api/src/functions/`: - `hello.ts` — `handleRequest` export, returns `{ data, url }` - `legacyHello.ts` — legacy handler export, returns `{ data }` - Both created by step 11 of `tasks/test-project/rebuild-test-project-fixture.mts` - Secrets `NETLIFY_SITE_ID` and `NETLIFY_AUTH_TOKEN` are set as GitHub secrets