👣 docs: Define CJS and Jotai Migration Triggers (#15756)

Both migration rules described an end state and left the trigger implicit, which is why they get skipped.

"Keep /api changes to the absolute minimum" reads as "make a small edit here", the opposite of what it means, and it is phrased for new code while the common case is editing an existing CJS file. It now says /api holds wiring and not behavior, that minimum describes how much behavior /api gains rather than diff size, and that lifting the function out is the larger and correct diff. MCPRequestContext.js is named as the shape.

"Convert the areas you touch" never defined an area, and never said an atom cannot be half converted, so mixed Recoil and Jotai imports in one file read as permission. The rule now states that new state is always Jotai, that the unit of conversion is one atom plus every reader and writer, and that an atom with a consumer outside the feature stays on Recoil and gets passed in. jotai-utils.ts is named for persisted atoms.
This commit is contained in:
Danny Avila 2026-09-08 22:20:14 -04:00 • committed by GitHub
parent a353e117bc
commit e6376f6df4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 32 additions and 7 deletions

View file

@ -50,6 +50,12 @@ changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typec
## Module boundaries and configuration
`/api` holds wiring, not behavior. When a change would add logic to a CJS file there — a branch, a
helper, a validation step, a service call — the logic belongs in `packages/api`, and the JS file
keeps requires, route registration and the call into the TS module (`MCPRequestContext.js` is the
shape, thirteen lines of re-export). "Minimum" means how much behavior `/api` gains, not how small
the diff is, and the rule applies to editing existing CJS, which is the common case.
Database contracts belong to `packages/data-schemas`. Keep Mongoose types (`FilterQuery`,
`Types.ObjectId`, `Document`) out of exported signatures in `packages/api`, `packages/data-provider`
and `client`, because they make the storage engine part of that module's public API. Take and return
@ -88,11 +94,15 @@ under “Auth cache invalidation”.
## Client state ownership
The client is migrating from Recoil to Jotai — convert the areas you touch, not the whole store.
The client is migrating from Recoil to Jotai. New state is always Jotai, even in a file that already
imports Recoil; many files import both, so mixed imports say nothing about which to use. For existing
state the unit of conversion is one atom plus every file that reads or writes it, because an atom
cannot be half converted — convert the areas you touch, not the whole store.
Split by ownership: state a feature both writes and reads is feature-owned, so convert it to Jotai
and keep it inside the feature; app-global preferences and shell state a feature merely consumes
(`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility) must be passed in
through props or a small host-supplied context rather than reached for through `~/store`. Passing
through props or a small host-supplied context rather than reached for through `~/store`; when a
consumer sits outside the feature you are changing, leave that atom on Recoil and pass it in. Passing
them in is what lets a feature move to its own workspace later without a rewrite, and it keeps the
Jotai conversion scoped to the state a feature owns. See the detailed policy in `CLAUDE.md` under
“Client State Ownership”.

View file

@ -21,7 +21,13 @@ The source code for `@librechat/agents` (major backend dependency, same team) li
## Workspace Boundaries
- **All new backend code must be TypeScript** in `/packages/api`.
- Keep `/api` changes to the absolute minimum (thin JS wrappers calling into `/packages/api`).
- **`/api` holds wiring, not behavior.** When a change would add logic to a CJS file under `/api` —
a branch, a helper, a validation step, a new service call — that logic goes in `/packages/api`,
and the JS file keeps only what wires it up: requires, route registration, request plumbing, and
the call into the TS module. `api/server/services/MCPRequestContext.js` is the shape, at thirteen
lines of re-export. "Minimum" describes how much behavior `/api` gains, not how small the diff is:
lifting a function into `/packages/api` and calling it is the larger diff and the correct one.
Editing an existing CJS file is the common case and the rule applies there, not only to new files.
- Database-specific shared logic goes in `/packages/data-schemas`.
- Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`.
- Build data-provider from project root: `npm run build:data-provider`.
@ -261,15 +267,24 @@ Multi-line imports count total character length across all lines. Consolidate va
### Client State Ownership
The client is migrating from Recoil to Jotai. Convert the areas you touch rather than
migrating wholesale, and split the work by who owns the state:
The client is migrating from Recoil to Jotai. **New state is always Jotai**, including inside a file
that already imports Recoil. For existing state, the unit of conversion is one atom together with
every file that reads or writes it: the two libraries hold different atom objects, so an atom cannot
be half converted, and many files already import both — mixed imports are not a signal that either
choice is fine here. Convert the areas you touch rather than migrating wholesale, and split the work
by who owns the state:
- **Feature-owned state** — atoms a single feature both writes and reads. Convert these to
Jotai as you touch them, and keep them inside the feature.
Jotai as you touch them, with all of their consumers, and keep them inside the feature.
`client/src/store/jotai-utils.ts` carries the equivalents for persisted atoms
(`createStorageAtom`, `createStorageAtomWithEffect`, `createTabIsolatedAtom`), so a Recoil atom
with a localStorage effect has a direct port.
- **App-global state** — preferences and shell state a feature merely consumes
(`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility). A feature
that could plausibly be extracted must not reach into `~/store` for these; accept them
through props or a small context the host supplies.
through props or a small context the host supplies. When a consumer sits outside the feature you
are changing, leave the atom on Recoil and pass it in — do not convert the shell to make one
feature tidy.
Passing app-global state in — rather than reaching for it — is what lets a feature move to
its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the