DX friction points found while extending a scaffolded app (codegen timing, implicit gql, cell naming convention, operation-name collisions)

[Tobbe]

This issue was posted by an AI Agent 🤖

While making a small feature addition to a scaffolded CedarJS app (adding a filtered
message feed alongside the standard scaffold CRUD pages), I ran into a few points of
friction. None were blocking, but each cost time figuring out "why doesn't this work"
before finding the convention. Writing them up together since they're all DX/discoverability
issues rather than bugs.

1. yarn cedar g types isn't wired into build/dev. After adding a new GraphQL query
   field and referencing its generated type in a web component, running yarn cedar build
   before regenerating types would fail with a confusing "type doesn't exist" error, with
   no hint that the fix is to run codegen. Could build/dev auto-run codegen when SDL
   files change, or at least surface a clearer error pointing at g types?

2. gql is an implicit global with no visible origin. Every cell/query file uses
   gql`...` with no import. Presumably injected via a babel/vite transform, but the
   file itself gives no indication where it comes from, which trips up linters, IDEs, and
   anyone reading a single file in isolation. A visible re-export (e.g.
   import { gql } from '@cedarjs/web') would make files self-describing at no cost.

3. Cell directory/filename convention has no discovery aid outside the generator.
   SomeCell/SomeCell.tsx only resolves because the filename matches the directory name —
   there's no barrel file or manifest, so the only way to learn this is by reading existing
   generated examples. If you hand-author a new cell (rather than running
   cedar generate cell), a naming mismatch fails silently/confusingly. A lint rule or a
   clearer runtime error would help.

4. No collision check on GraphQL operation names. Apollo's cache dedupes by operation
   name. Cells generated for the same underlying query but with custom names (e.g. adding a
   second, differently-shaped cell against messages) can silently collide if named the
   same as an existing operation, causing wrong cached data to be returned rather than a
   build-time error. Would be great to catch this at codegen time.

5. Minor: yarn rw ... still works but prints a deprecation notice pointing at
   yarn cedar. Worth sweeping docs/scaffolded comments that might still reference the old
   command, since it's easy to copy-paste old muscle memory.

6. No scaffolded AGENTS.md/CLAUDE.md to teach AI agents (or new devs) when to reach
   for a Cell vs. raw useQuery. I initially reached for useQuery directly for a small
   auxiliary fetch (a dropdown's option list) purely out of habit from generic React/Apollo
   codebases, not because it was the right call — a Cell would have given me its
   Loading/Empty states for free. When asked about it, the framework author clarified that
   Cells are meant to be the natural default, with useQuery as an intentional escape
   hatch for cases Cells don't cover — and in practice that's a narrower set than I assumed,
   since on-demand refetch (queryResult.refetch in Success/Loading/Failure) and
   polling (via pollInterval returned from beforeQuery, see beforeQuery's return type only declares { variables }, but the runtime passes it through as full useQuery options #2378) are both already
   handled by Cells. A generated AGENTS.md/CLAUDE.md in new apps (create-cedar-app
   templates) stating this explicitly would let agents (and skimming humans) get it right
   from the start instead of discovering it by reading existing example files. Suggested
   wording:

   ## Data fetching
   
   Cells (`src/components/**/*Cell`) are the default way to fetch data in this app —
   reach for one first. Generate with `yarn cedar generate cell <Name>`. A Cell gives you
   Loading/Empty/Failure states for free, its `Success`/`Loading`/`Failure` components
   receive a `queryResult` prop with `refetch`/`fetchMore` already wired up, and
   `beforeQuery` can return extra `useQuery` options (e.g. `pollInterval`) for polling.
   
   Only drop to `useQuery`/`useMutation` directly when a Cell genuinely can't express what
   you need — e.g. firing a query imperatively outside of render, or logic tightly coupled
   to custom component state/effects that doesn't fit the Loading/Empty/Failure/Success
   shape. If you're about to write `useQuery` inside a page or component, pause and check
   whether a Cell would cover it first.

[Tobbe]

Re claim 4 / eslint vs yarn cedar check:

Best fit is a yarn cedar check diagnostic in @cedarjs/structure, not an eslint rule.

• eslint is per-file — current packages/eslint-plugin/src has 3 per-file rules. Duplicate operation names need project-wide aggregation across RWProject.cells (packages/structure/src/model/RWProject.ts), which is awkward to do correctly in lint.
• structure already does this — RWCell.queryOperationName (packages/structure/src/model/RWCell.ts:57) is parsed and RWCell.diagnostics() already warns on missing name (RWCell.ts:80) via collectDiagnostics() / printDiagnostics() (packages/structure/src/index.ts:17, packages/cli/src/commands/check.ts). Grouping by operation name and yielding a DiagnosticSeverity.Warning for duplicates is a natural extension there.
• For context on claim 4: generate-time does guard (packages/cli/src/commands/generate/cell/cellHandler.ts:89 + packages/cli/src/commands/generate/cell/utils/utils.ts:15 auto-suffixes), but hand-edited duplicates after generation slip through — no build/g types/lint warning today.

Caveat: check is currently marked experimental and isn't auto-run by lint/build (packages/cli/src/commands/lint.ts, packages/cli/src/commands/build/buildHandler.ts), so for discoverability it may want surfacing in g types/build too — but the primary check belongs in structure.

[Tobbe]

For claim 5: #2387 and #2388 takes care of doc updates. We now say yarn cedar everywhere we should. As for the deprecation warning, I think that's actually the best thing we can do. It's exactly what tells anyone that still runs yarn rw that there exists a new binary that should be used instead.

[lisa-assistant]

Implementation plan

Six separate friction points here — I dug into each against current main. #5 is already resolved (docs swept in #2387/#2388, and the yarn rw deprecation notice is intentional per Tobbe's comment above), so I'm skipping it. Concrete plans for the rest:

1. g types not wired into build/dev

Confirmed: yarn cedar g types (packages/cli/src/commands/generate.ts line 32) shells out to a separate cedar-gen bin and is never invoked from packages/cli/src/commands/build/buildHandler.ts or dev.ts. buildHandler.ts (~line 217) does have a conditional generate task, but it's gated on useFragments || useTrustedDocuments — it only regenerates possible-types/trusted-doc hashes, not the general SDL→TS types g types produces.

• Minimal fix: in buildHandler.ts, always run the equivalent of cedar-gen as an unconditional early task (not just the fragments/trusted-docs branch), before the type-checking/bundling steps that would otherwise fail with a stale-types error.
• dev.ts: no codegen step exists at all today. Given dev is long-running, a one-shot pre-flight cedar-gen run at startup (not a file watcher — that's a bigger scope) would at least remove the "just-added-a-query-field, build fails confusingly" case from the issue.
• Cheaper alternative if a maintainer doesn't want the codegen cost on every build/dev start: catch the specific TS error shape (Cannot find name/module 'X' for a types/graphql import) in the build's type-check failure path and print a hint pointing at yarn cedar g types, rather than actually running codegen. Worth raising as the two options rather than assuming full auto-run is wanted.

2. gql implicit global has no visible origin

Traced the injection: for Vite (the actual dev/build path), packages/vite/src/plugins/vite-plugin-cedar-auto-import.ts uses unplugin-auto-import with imports: [{ 'graphql-tag': ['gql'] }] (or the trusted-documents path) and dts: false (line ~57). unplugin-auto-import supports generating an auto-imports.d.ts with global ambient declarations when dts is a path instead of false — that's exactly the "visible origin" fix with zero runtime cost, since it's editor/typecheck-only.

• Fix: change dts: false to dts: path.join(cedarPaths.web.base, 'auto-imports.d.ts') (or wherever generated files already live) in vite-plugin-cedar-auto-import.ts, for all four autoImport({...}) calls (gql-web, context, gql-api, and the unimportPlugin.vite React one).
• Need to check the generated file gets added to .gitignore (likely already is, alongside other generated types/ files — check packages/create-cedar-app/templates/*/) and that TS project references pick it up (may need a include entry in the web tsconfig.json template).
• The Jest/non-Vite path (packages/babel-config/src/web.ts lines 108-135, babel-plugin-auto-import) has no dts equivalent since it's Babel not a Vite plugin generating types — out of scope for this fix, or would need a separate ambient .d.ts shipped in @cedarjs/web's types declaring declare const gql: ... behind a doc comment explaining the injection.

3. Cell naming convention discovery

packages/vite/src/plugins/vite-plugin-cedar-directory-named-import.ts (and its Babel counterpart packages/babel-config/src/plugins/babel-plugin-redwood-directory-named-import.ts) is where SomeCell/SomeCell.tsx resolution actually happens — worth reading its resolve-failure path first to see if a naming mismatch (e.g. SomeCell/Index.tsx) currently fails with a generic "module not found" or something more specific.

• A generic structure diagnostic (parallel to the item-4 approach below) checking RWCell-like directories (a dir containing a Cell-suffixed... file, or ending in Cell) for a filename/dirname mismatch would give a build-time/check-time warning rather than requiring readers to find existing examples. Smaller scope than a full lint rule since it's a single naming convention, not per-export typing.

4. No collision check on GraphQL operation names

Tobbe's comment above already nails the design — belongs in @cedarjs/structure, not eslint, since it needs project-wide aggregation. Concrete plan following that:

• packages/structure/src/model/RWProject.ts — cells getter (line 204) already returns RWCell[] for the whole project via globSync.
• Add a new diagnostic, likely as a project-level check (not per-RWCell.diagnostics(), since it needs to see all cells at once to detect collisions) — either a new method on RWProject (e.g. *duplicateOperationNameDiagnostics()) called from wherever project-level diagnostics are aggregated (packages/structure/src/nodes.ts collectDiagnostics, line 58), or folded into an existing project-wide check if one exists.
• Algorithm: group this.cells (plus likely this.sdls/queries outside Cells too, though the issue's example is Cell-specific) by queryOperationName (RWCell.ts line 57), and for any name with >1 distinct file, yield a DiagnosticSeverity.Warning (mirroring the existing "we recommend you name your query operation" warning at RWCell.ts lines 80-90) on each duplicate, pointing at the operation name's Range_fromNode.
• Surfacing: check command (packages/cli/src/commands/check.ts) picks this up automatically via printDiagnostics/collectDiagnostics (packages/structure/src/index.ts line 17, 26) since it walks the whole diagnostic tree. Per Tobbe's caveat, check is experimental and not auto-run by lint/build — so this alone won't close the loop the issue wants (catch it without manually running yarn cedar check). Worth a follow-up decision on whether to also surface in g types/build, but that's explicitly flagged as a separate, possibly-separate-PR question.

6. No scaffolded AGENTS.md/CLAUDE.md

No existing template file for this — packages/create-cedar-app/templates/ has ts/, js/, esm-ts/, esm-js/, overlays/ but nothing AI-agent-facing yet. Add AGENTS.md (the emerging cross-tool convention) at the root of each template variant (or in overlays/ if content is identical across variants, to avoid duplicating across ts/js/esm-*) using the wording drafted in the issue, verified/expanded with a pointer to the actual beforeQuery/pollInterval mechanics once #2378 (polling) lands. Check packages/create-cedar-app's file-copy logic to confirm dotfile-adjacent root files in templates/* are copied as-is (likely yes, same as README.md if one exists there).

Suggested scope

Items 2 and 4 are the most self-contained and lowest-risk to land independently; 1 needs a maintainer decision on auto-run vs. better-error-message; 3 and 6 are smaller but need a companion PR each. I'd split these into separate PRs rather than one mega-PR, given the issue itself frames them as independent friction points.

[lisa-assistant]

Confidence: 4/10

This is really six loosely-related asks bundled into one issue, and my confidence varies a lot by item: high for #2 (dts flag flip) and #4 (Tobbe already spec'd the approach precisely), moderate for #6 (just needs content + a file-copy check), and low for #1 and #3 where I'm proposing a direction but a maintainer needs to pick between "auto-run codegen" vs. "better error message" (item 1) and I haven't fully traced the directory-named-import resolver's failure path to know what UX already exists (item 3). Given the scope, I'd expect this to land as several small PRs rather than one, and each would need its own back-and-forth before merge.