Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
👣 docs: Define CJS and Jotai Migration Triggers (#15756)
Danny Avilae6376f6df4e5
diff --git a/AGENTS.md b/AGENTS.mdindex 6db760e607..da0c9b75a8 100644--- a/AGENTS.md+++ b/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 Jotaiand 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. Passingthem in is what lets a feature move to its own workspace later without a rewrite, and it keeps theJotai conversion scoped to the state a feature owns. See the detailed policy in `CLAUDE.md` under“Client State Ownership”.diff --git a/CLAUDE.md b/CLAUDE.mdindex b4ff8546d8..389554a231 100644--- a/CLAUDE.md+++ b/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 featurethat 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 toits own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the