mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 15:33:45 +00:00
👣 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:
parent
a353e117bc
commit
e6376f6df4
2 changed files with 32 additions and 7 deletions
14
AGENTS.md
14
AGENTS.md
|
|
@ -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”.
|
||||
|
|
|
|||
25
CLAUDE.md
25
CLAUDE.md
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue