* 🎨 feat: Check Color Tokens and Class Existence Moves the Tailwind colors out of createTailwindColors() and into packages/client/src/theme/tokens.css as `@theme inline`, published as @librechat/client/theme.css and imported by the app's stylesheet. Runtime theme switching is unchanged: each token still resolves to the custom property ThemeProvider rewrites, and `@theme inline` is what keeps it out of a frozen variable. The palette scales are closed, so an undeclared shade is no longer a color. Reading the tokens is what lets @shadcn/lint check them, so no-unknown-classes goes on and no-raw-colors gains undeclared-token detection. Between them they found dead classes the app has been shipping: 59 `token-`-prefixed color classes that generate nothing, `transition-color`, `scrollbar-hide`, `pointer-cursor`, `mt-text-sm`, `dark:gpt-dark-gray`, `-ml-0.9`, `-mt-0.8`, `transition-width` and `overflow-anchor-none`, all repaired or removed here. The library's own config gains tailwindcss-animate, since its components write `animate-in` and the accordion keyframes. * 🧽 refactor: Delete the Plain `*-token-*` Rules the Tokens Replace `client/src/style.css` defined `.text-token-text-{primary,secondary,tertiary}`, `.border-token-border-{light,medium}` and `.bg-token-surface-secondary` as plain rules, so the 63 call sites this pull request renamed were painting their token rather than nothing. The rules have no consumer left once the names are gone, and they sat outside `@layer utilities`, where an unlayered rule beats every utility on the same property: keeping them would hold that cascade for any class attribute that reintroduced a name. Deleting them is what lets the variants written beside those classes apply — the entity avatars take `dark:bg-surface-tertiary` in dark mode, and the two action-header fields take `hover:border-border-heavy` on hover. Two files the rename touches carried lint debt the changed-file gate attributes to this pull request once they appear in the diff: `ActiveSetting.tsx` was an unreferenced mock component whose hard-coded copy fails `i18next/no-literal-string`, and `Retrieval.tsx` computed a `vectorStores` value nothing reads. Both are removed. `tokens.spec.ts` takes its `structuredClone` polyfill and its Tailwind module loader through imports, which `@typescript-eslint/no-require-imports` requires of a TS file. * ✅ test: Cover the Token Utilities From a Browser Whether an element still takes its token color after the plain rules are gone is only answerable in a rendered page, so the four behaviours this change turns on get a tagged scenario in the mock harness: the account-menu email resolves `--text-secondary` instead of inheriting the menu's primary text color, a theme definition installed at load recolors that same row to its own value (what `@theme inline` exists for), the mention menu's frame resolves `--border-light` rather than falling back to `currentColor`, and the login email field transitions `color`/`border-color` for 200 ms instead of `all`, which is what `transition-color` left it doing. Each reads the theme's custom properties through the browser rather than restating a hex, so the same assertions hold in light mode, dark mode and mobile emulation. * 🩹 test: Settle the Shell Before Locating the Account Button Probing `nav-user` visibility straight after `goto` reports the desktop sidebar as absent, because nothing has rendered yet, and the fallback then waited on the mobile-only header toggle until the test timed out — the two account-menu scenarios failed that way on both desktop projects while passing on mobile. Waiting for the composer first settles the shell, and the fallback click carries a timeout so a missing toggle fails fast instead of hanging. * 🩹 test: Open the Drawer Before Reaching the Account Button Below `md` the account button renders inside the drawer's own header, off-canvas until the toggle opens it: a locator calls it visible, a click waits for it to stop moving, and the two account-menu scenarios timed out on the mobile project. The toggle is `md:hidden`, so its own visibility is the layout probe — click it when it is there, then the button is reachable in both layouts. * 📝 docs: Point the Theme Setup and the Lint Contract at What Ships The theme README's setup still told a consumer to rebuild the color map in `theme.extend.colors` — the map this change deletes — and never mentioned the published stylesheet, so following it leaves the semantic utilities ungenerated. Steps 3 and 4 now import `@librechat/client/theme.css` and the config keeps only content, dark mode and the preset, with the removal called out as the breaking change it is. `CLAUDE.md` said five design rules run and that `no-unknown-classes` stays off because the repository is on Tailwind 3.4; this change enables it. That section now describes six rules, what the rule cannot see and therefore what the `allow` list is for, that `no-raw-colors` also reports an undeclared token, and the distinction a reviewer needs for this diff: a raised suppression count usually means a new override, but a rule that starts resolving class names it used to skip reports styling the tree already carried. * 🩹 fix: Publish the Token Stylesheet as a File, Not a Folder tsdown's `copy` reads `to` as a destination directory, so `{ from: 'src/theme/tokens.css', to: 'dist/theme.css' }` produced `dist/theme.css/tokens.css` — a directory where the package's `./theme.css` export pointed, which makes `@import '@librechat/client/theme.css'` fail for every consumer of the published package. The copy now keeps the file's name in `dist` and the export maps `./theme.css` onto `./dist/tokens.css`; `require.resolve('@librechat/client/theme.css')` answers with that file after a build. The app is unaffected either way, because `client/src/style.css` imports the tokens from source so a lint or CI run needs no prior build — which is exactly why nothing here noticed. * 🎨 fix: Give the Bash Command Pane the Code Surface Role Repairing `dark:bg-gray-950` by swapping in this palette's darkest shade kept the pane on a raw value: `gray-900` is a scale entry, so no theme — custom, high contrast, or a future one — can recolor a surface that every other code pane takes from `surface-code` (`DiffView`, the user-turn code bars). It now takes that role in both modes, which also drops the light/dark split the element carried for no reason. Appearance moves with it: dark goes to `#212121` instead of `#0d0d0d`, light to `#f7f7f8` instead of `#ececec`, matching the diff pane directly above it in the same card. * 🩹 fix: Stop Hand-Copied Tailwind Rules From Outranking Their Utilities `client/src/style.css` carried a block of Tailwind's own v2/v3 output copied in by hand — `.hidden`, `.overflow-y-auto`, `.overflow-x-auto`, `.truncate`, `.text-ellipsis`, `.animate-spin`, `.grow` and a `--tw-*`-based `.transform`. Under v3 those sat beside the generated utilities and lost to anything later in the sheet. Under v4 the utilities live in `@layer utilities` and these rules do not, so they beat every utility for their property, variants included: `hidden sm:flex` and `hidden md:flex` resolve to `display: none` at every width. Two surfaces were gone because of it. The welcome screen's disclaimer (`Chat/Footer.tsx`, `hidden … sm:flex`) never appeared, and the header's right-hand control cluster (`hidden items-center gap-2 md:flex`) took the bookmark menu and the temporary-chat toggle with it. `scenarios/welcome-disclaimer.spec.ts`, `scenarios/temporary-chat-icon.spec.ts` and `bookmarks.spec.ts` fail on the parent branch's build and pass here; nothing else in the style-sensitive e2e set changes. Tailwind generates every declaration removed here, so the only behavioural difference is `overflow: overlay`, which the copies set and which Chrome has aliased to `auto` for years and other engines never implemented. * 📝 docs: Load the Documented Tailwind Config From the Documented Stylesheet v4 reads no config file unless a stylesheet says so, and the setup's step 3 imported the tokens without an `@config` line, so the config step 4 tells a consumer to write — the preset, the `content` globs, class-based dark mode — never applied. Both of this repository's own entries carry the directive (`client/src/style.css`, `packages/client/src/theme/theme.css`); the example now does too, and step 4 says that the file only takes effect through it. * ✅ test: Cover the Token Checks and the Published Stylesheet From a Browser Two `@scenario`-tagged specs for what this change turned on. The first asks the flat config, through a stdin probe, what a caller hears for a class Tailwind cannot generate (`transition-color`) and for a colour token nobody declared (`bg-surfce-primary`): both rules report, both name the spelling the author meant, and the correctly spelled neighbours stay silent, which is what makes the report about those two classes rather than about the probe. The second resolves the `./theme.css` export the way a bundler does and asserts it lands on a file that declares the `@theme inline` tokens and ships inside the package's `files` — the export resolved to a directory once, and a consumer's `@import` is where that failed. * 🩹 fix: Record the Backlog the Rebase Brought Into the Enabled Rules The 28 `dev` commits this stack caught up with added styling to three files the full-tree sweep lints, and the recorded counts predate them: `ToolApproval.tsx`, `Chat/Trace/Viewer.tsx` and the `TemplateTable.tsx` mockup reported through the baseline, which is what the ESLint config regression gate compares. Those violations are `dev`'s existing styling arriving in the rules' scope, so they are recorded rather than restyled, and the count in CLAUDE.md follows. * 🩹 fix: Ship the Animation Plugin With the Preset Consumers Load The components published here write `animate-in`, `fade-in-0`, `zoom-in-95` and `slide-in-from-*` — dialogs, popovers and dropdowns — and those are `tailwindcss-animate` utilities. The plugin was registered only in `packages/client/tailwind.config.js`, which is neither exported nor in the package's `files`, so a consumer following the documented setup loaded the preset and got no CSS for any of them: the surfaces appeared without their motion and nothing said why. The preset registers the plugin, `tailwindcss-animate` joins `tailwindcss` and `tailwind-merge` as a peer dependency, and the consumer contract says so. The new `@scenario:the-published-preset-generates-the-components-animations` compiles the preset the way a consumer's build does — no app config — and requires CSS and keyframes for each of those classes, with `p-4` as the control. * 🩹 fix: Point the Documented Consumer Globs at the Files That Ship Step 4 of the theme README handed a consumer `./node_modules/@librechat/client/dist/**/*.js` as the content glob that reaches this package. `tsdown.config.mjs` sets `fixedExtension: true`, so `dist` holds `index.mjs` and `index.cjs` and never a `.js` — the glob matched zero files. A consumer following the documented setup scanned only their own `src`, so every utility that appears exclusively in a published component (dialog, menu, button surfaces) was generated for nobody. The SPA never saw it: `client/tailwind.config.cjs` scans `../packages/client/src`, the source, not the built package. The glob now reads `dist/**/*.{js,mjs,cjs}`, and a scenario reads it back out of the README rather than restating it, so the prose and the shipped file names cannot drift apart again: it resolves the globs against the built package and asserts they match every javascript module the export map points into `dist`, and that those modules really do carry class names to find. Against the previous README the same glob expansion matches `[]`; against this one it matches `dist/index.mjs` and `dist/index.cjs`. * 🩹 fix: Settle the Baseline, the Peer Metadata and the Comment the Rules Left Three records that disagreed with the code they describe, all of them surfaced by this pull request's own CI lane on a81c4a3. `eslint-suppressions.json` recorded 10 `no-restyle` violations for `client/src/components/Chat/AddMultiConvo.tsx` while the file has 9: the base branch repaired one (`blur-sm` → `blur-xs` in a3e450de) without re-recording, and this branch's baseline commit replayed the stale count over it. The suppressions validator reads the whole baseline once the file is in the diff, so it failed the Static Checks job with exactly that line. `npm run lint:design:prune` drops the unused one; the trailing newline the runner strips is restored. `package-lock.json` never received the two peers `packages/client/package.json` declares: `tailwindcss` (added on the base branch) and `tailwindcss-animate` (added here). The resolved tree was already correct — `tailwindcss-animate@1.0.7` is hoisted — but the workspace entry's `peerDependencies` block disagreed with its manifest. `npm install --package-lock-only` adds the two lines and changes nothing else. `eslint.config.mjs` still explained, four lines above the rule, that `no-unknown-classes` "is deliberately not enabled" because "this repo runs tailwindcss 3.4 with a JS preset". It is enabled at error on line 268, and the comment beside the rule already says why that is now answerable. * 🩹 fix: Import the Token Stylesheet Where the Consumer Probe Compiles The standalone-consumer scenario compiled `@import 'tailwindcss'` plus the package's config and nothing else, which is where the colours used to come from: `createTailwindColors()` spread them into `theme.extend.colors`. They are declared in `tokens.css` as `@theme inline` now, so that entry emitted no `border-border-light` at all — compiled here, the class count is 0 — and the divider fell back to `currentColor`, failing the e2e lane on shard 3 with the text ink (`rgb(200, 0, 0)`) where the border role belongs. The probe now imports the published token stylesheet between Tailwind and the config, which is step 3 of the theme README and what a consumer following it writes; the path comes from the package's own `./theme.css` export so it cannot drift from what ships, and the build guard requires that file too. With the import the utility compiles as `border-color: rgb(var(--border-light) / var(--border-light-alpha, 1))`, and the radius assertions are untouched: `rounded-sm` still resolves `calc(var(--radius, 0.5rem) - 0.375rem)`. The scenario joins this change's acceptance contract, because the invariant it now protects is this one's: a consumer gets the package's colours from the stylesheet, not from a config block. * 🧽 refactor: Stop the Dashed Avatar Border From Depending on Emission Order Both avatar placeholders carried `border-border-medium` and `border-black` on one element. Same specificity, so the winner is whichever Tailwind emits last, and compiling this tree's own config puts `.border-black` at line 3021 and `.border-border-medium` at 3042 — the token wins today, which is why the placeholders looked unchanged through the rename. Nothing states that order, so a change in how Tailwind sorts utilities would silently turn the border black. `border-black` is deleted at both sites. The border keeps painting `border-border-medium` exactly as it does now, and the recorded counts do not move: neither file has a `no-raw-colors` entry, and the suppressions validator stays green over the 74-file diff. * 🎞️ fix: Preserve Component Animations When Integrating Canary * 🎛️ fix: Let Shared Primitives Own Input and Tab Styling * 🔗 fix: Preserve Auth Link Color Transitions * 🧪 test: Verify Auth Link Color Transitions * fix: Preserve Semantic Color Enforcement and Consumer Setup * fix: Preserve Consumer Tailwind Palettes * fix: Copy the Compatibility Palette Into the Docker Client Build --------- Co-authored-by: berry-13 <berry-13@users.noreply.github.com>
30 KiB
LibreChat
Project Overview
LibreChat is a monorepo with the following key workspaces:
| Workspace | Language | Side | Dependency | Purpose |
|---|---|---|---|---|
/api |
JS (legacy) | Backend | packages/api, packages/data-schemas, packages/data-provider, @librechat/agents |
Express server — minimize changes here |
/packages/api |
TypeScript | Backend | packages/data-schemas, packages/data-provider |
New backend code lives here (TS only, consumed by /api) |
/packages/data-schemas |
TypeScript | Backend | packages/data-provider |
Database models/schemas, shareable across backend projects |
/packages/data-provider |
TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend |
/client |
TypeScript/React | Frontend | packages/data-provider, packages/client |
Frontend SPA |
/packages/client |
TypeScript | Frontend | packages/data-provider |
Shared frontend utilities |
The source code for @librechat/agents (major backend dependency, same team) lives at
https://github.com/danny-avila/agents.
Workspace Boundaries
- All new backend code must be TypeScript in
/packages/api. /apiholds 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.jsis the shape, at thirteen lines of re-export. "Minimum" describes how much behavior/apigains, not how small the diff is: lifting a function into/packages/apiand 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. - Database contracts stay inside
/packages/data-schemas. A Mongoose type in an exported signature —FilterQuery,Types.ObjectId,Document,HydratedDocument— makes the storage engine part of that module's public API, and every consumer then depends on Mongo instead of on the data it needs. Take and return plain typed objects, and express the query behind a data-schemas method. The boundary already leaks across dozens of files in/packages/api, so the rule is to stop widening it rather than to rewrite what exists;/clientcarries none of it and must stay that way. - New levers ship configurable. A limit, timeout, toggle or capability introduced in code earns
a field on
configSchema(packages/data-provider/src/config.ts) so an operator can set it inlibrechat.yaml, with a default that reproduces today's behavior. Hard-coded constants and env-only switches need a reason. The schema is also what keeps one definition of the value instead of a constant, a fallback and a doc line that drift apart. - A backend module takes its dependencies, it does not reach for them. Code in
/packages/apishould receive its config, database methods and clients from the caller the waycreateModels(mongoose)receives the app's connection, rather than importing app singletons or reading global state. A module the caller constructs can be tested without a running app and moved to another workspace without a rewrite; one that callsgetInstance()can do neither. This is the backend half of "Client State Ownership" — pass it in, do not reach for it. The static singletons underpackages/api/src/mcpare the shape to stop extending, not a pattern to copy. - Integrations arrive through an interface the caller supplies. A provider SDK, storage backend, vector store or OAuth server is injected, so a second implementation is a new argument instead of a new branch in shared code, and a test can exercise the real logic against a substitute at the boundary rather than mocking the module that holds it.
Branching and Pull Requests
- Branch off
dev, and targetdevwith every pull request. All work lands ondevfirst. mainis the released branch. It is kept as a fast-forward ofdevand synced as-is, so it is always an ancestor ofdev— equal to it right after a sync, behind it otherwise. It never carries a commit thatdevdoes not have.- Never open a backport pull request to
main. Anything merged todevreachesmainat the next sync; a second pull request for the same change is redundant. - The repository's default branch is
main, sogh pr createand the GitHub UI target it unless told otherwise — always pass--base devexplicitly. - Pull requests opened against
mainare retargeted todevautomatically by.github/workflows/pr-retarget-dev.yml. Thetarget: mainlabel exempts one, as do release-bound upstream branches (dev,release/*,hotfix/*). Backport branches are deliberately not exempt — a backport merged straight tomainis what breaks the fast-forward invariant. Fixes #Ndoes not close the issue. GitHub honors closing keywords only when a pull request merges into the default branch (main). Merging todevdoes not close anything, and the later fast-forward ofmainis not a merge event either — close linked issues by hand.- Git worktrees share one stash stack.
refs/stashlives in the common.gitdirectory, so a baregit stash popin one worktree can take work stashed in another. Prefer a throwaway WIP commit; if you must stash,git stash push -m <tag>andapplythat specific entry. - Write the description for a reader who has not followed the branch. Say what breaks, what
triggers it, and how it behaves after the change, then show the mechanism with whichever one or
two views make it reviewable — a focused diff, a call tree, a shallow file tree, or a Mermaid
sequence — keeping only the calls, files and state the change actually carries. Describe the code
as it stands: do not narrate what earlier commits tried or what a review round changed. Naming the
merged pull request that caused the bug is different — that is history the reader needs.
.github/pull_request_template.mdcarries the formats and examples.
Review and Completion
AI review cycles
The reviewer, its trigger phrase and its cadence all change; this subsection is the fluid one, so rewrite it when they do. What survives a change of tool: a review counts only for the exact commit it ran on, its findings are judged against the code rather than accepted or dismissed wholesale, and findings that keep arriving mean the subsystem needs a sweep, not another patch.
- Inline review threads are the source of truth. A summary comment, a check name or a notification list omits findings — read the threads on the pull request itself.
- Audit every finding against the current code. Fix the valid ones; reject the obsolete or wrong ones in a reply that says why.
- After each round of fixes, run the focused tests and
npx tsc --noEmitfor every workspace you changed, push, read the pull request's remote head (gh pr view <n> --json headRefOid), and request the next review naming that exact SHA. A clean review of an earlier head says nothing about what you just pushed. Do not wait for CI before asking — review and CI run on their own clocks. - Reply on each thread you resolved with the commit that resolved it and the coverage that proves it.
- After two actionable rounds — or sooner, when each fix uncovers an adjacent defect — stop answering threads one at a time and read the subsystem by invariant: identity, ownership, authorization, persistence, retry, replay, abort, cleanup, expiry, rollout. Follow producers, consumers, adapters, alternate write paths, and the final consumer of every limit; check mixed-version behavior in both directions; read the whole base-to-head diff with the callers and tests around it; then add transition or failure-injection coverage at the deepest boundary that owns the behavior.
- The cycle ends when the exact pushed head draws no major findings, or only repeats ones already resolved. A clean review is one completion signal, not the definition of done.
Definition of done
- Ship the observable experience, not the reported path. Where they apply, cover loading, empty, success, failure, cancellation, retry and restored-session behavior.
- A backend capability with no frontend entry point is unfinished, and so is a control with no validation, persistence, error handling or authorization behind it.
- Localize every visible string through
useLocalize(), keep semantic HTML, keyboard behavior and ARIA intact, and compose shared primitives and semantic theme roles before adding local styling (see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and reduced motion. - Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior,
and expose any new lever through
configSchemarather than a constant (see "Workspace Boundaries"). - Make the fix the smallest one consistent with the patterns already in the file, and test the behavior that was missed rather than the line a reviewer pointed at.
- Report what you actually ran: the pushed head, the local checks from "Testing" and "Typechecking", CI state, the review result at that head, and any finding you rejected with the reasoning. Name the checks you could not run instead of implying coverage.
Code Style
Naming and File Organization
- Single-word file names whenever possible (e.g.,
permissions.ts,capabilities.ts,service.ts). - When multiple words are needed, prefer grouping related modules under a single-word directory rather than using multi-word file names (e.g.,
admin/capabilities.tsnotadminCapabilities.ts). - The directory already provides context —
app/service.tsnotapp/appConfigService.ts.
Structure and Clarity
- Never-nesting: early returns, flat code, minimal indentation. Break complex operations into well-named helpers.
- Functional first: pure functions, immutable data,
map/filter/reduceover imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation. - No dynamic imports unless absolutely necessary.
DRY
- Extract repeated logic into utility functions.
- Reusable hooks / higher-order components for UI patterns.
- Parameterized helpers instead of near-duplicate functions.
- Constants for repeated values; configuration objects over duplicated init code.
- Shared validators, centralized error handling, single source of truth for business rules.
- Shared typing system with interfaces/types extending common base definitions.
- Abstraction layers for external API interactions.
Iteration and Performance
- Minimize looping — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale.
- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined.
- Choose data structures that reduce the need to iterate (e.g.,
Map/Setfor lookups instead ofArray.find/Array.includes). - Avoid unnecessary object creation; consider space-time tradeoffs.
- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references.
Backend Database Performance
- On request startup and first page load paths, watch for serial database reads. Multiple round trips to MongoDB can add significant latency when the database is far from the app server.
- Prefer passing already-loaded request/user/config data through helper functions instead of re-reading the same user, role, tenant, or principal data.
- When two reads are independent, start them in parallel and gate the response on the authorization or validation result before returning data.
- Keep authorization, permission, and tenant checks semantically identical when parallelizing reads. Speculative reads must remain scoped to the authenticated user or tenant and must not write to the response before validation succeeds.
Type Safety
- Never use
any. Explicit types for all parameters, return values, and variables. - Limit
unknown— avoidunknown,Record<string, unknown>, andas unknown as Tassertions. ARecord<string, unknown>almost always signals a missing explicit type definition. - Don't duplicate types — before defining a new type, check whether it already exists in the project (especially
packages/data-provider). Reuse and extend existing types rather than creating redundant definitions. - Use union types, generics, and interfaces appropriately.
- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics.
Comments and Documentation
- Write self-documenting code; no inline comments narrating what code does.
- JSDoc only for complex/non-obvious logic or intellisense on public APIs.
- Single-line JSDoc for brief docs, multi-line for complex cases.
- Avoid standalone
//comments unless absolutely necessary.
Import Order
Imports are organized into three sections:
- Package imports — sorted shortest to longest line length (
reactalways first). import typeimports — sorted longest to shortest (package types first, then local types; length resets between sub-groups).- Local/project imports — sorted longest to shortest.
Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone import type { ... } — never inline type inside value imports.
JS/TS Loop Preferences
- Limit looping as much as possible. Prefer single-pass transformations and avoid re-iterating the same data.
for (let i = 0; ...)for performance-critical or index-dependent operations.for...offor simple array iteration.for...inonly for object property enumeration.
Frontend Rules (client/src/**/*)
Localization
- All user-facing text must use
useLocalize(). - Only update English keys in
client/src/locales/en/translation.json(other languages are automated externally). - Semantic key prefixes:
com_ui_,com_assistants_, etc.
Components
- TypeScript for all React components with proper type imports.
- Semantic HTML with ARIA labels (
role,aria-label) for accessibility. - Group related components in feature directories (e.g.,
SidePanel/Memories/). - Use index files for clean exports.
Theming and styling
- Compose before styling. Search
@librechat/clientfor an existing primitive, semantic variant, or composition before adding feature-local classes or CSS. - Use semantic roles. Colors and shared appearance values must come from the semantic Tailwind/theme roles. Do not add raw palette utilities, hard-coded hex/RGB/HSL colors, or light/dark-specific values in feature components.
- Deepen the system when the need is reusable. Add a focused variant to a shared primitive or extend the canonical, versioned theme-token registry when multiple screens should share the same design decision. Do not create shallow local wrappers that merely relocate class strings.
- Themes are data, not arbitrary CSS. Theme definitions may select semantic colors and shared appearance roles. They must not contain selectors, arbitrary CSS, application behavior, or alternate feature layouts. Preserve existing environment and stored-theme compatibility when changing the theme engine.
- Keep layout and behavior local. Feature structure, responsive layout, state-driven transitions, and specialized visualization may remain feature-owned. Expose a theme role only when it represents a stable, reusable appearance decision; do not turn every measurement into a global token.
- Treat custom CSS as an exception. Use it only when shared primitives and semantic utilities cannot express the requirement. Keep it narrowly scoped, consume theme variables where applicable, support light/dark and reduced motion, and add a brief code or PR explanation of why the exception is necessary.
- Preserve defaults and prove variability. New theme-aware variants must reproduce the current default appearance unless a redesign is explicitly requested. Test semantic-token use and, when extending theme capabilities, include a deliberately different reference theme to prove that components adapt without feature-specific overrides.
- The design rules are enforced by
npm run lint.@shadcn/lintis registered ineslint.config.mjsforclient/src/**andpackages/client/src/**. It resolves@librechat/client(and the~/components/uire-exports) as the design system, reads each primitive'scvavariants, and reports aclassNamethat overrides what the primitive owns — naming the variants, sizes and defining file to use instead. Six rules run aterror:no-restyle(layout andicon-*sizing allowed),no-raw-colors,no-arbitrary-values(layout allowed),no-inline-styles(measured geometry allowed: width, height, inset, transform, z-index),require-static-classesandno-unknown-classes. The last one asks the installed Tailwind whether a class generates any CSS, which needs v4 and the color tokens in CSS (packages/client/src/theme/tokens.css) for the rule to resolve a theme; under 3.4 its fallback reported every preset utility (duration-theme-fast,rounded-theme-control) as a typo. What it cannot see is a class defined in a stylesheet Tailwind does not read, or one a dependency puts in the DOM, so those live in itsallowlist ineslint.config.mjs, add a name there when a plain selector or a third party owns it, and fix the class when nothing defines it.no-raw-colorsadditionally reports abg-/text-/border-name whose token is not declared in the theme, which is the same failure wearing a color's clothes. - Contracts say what a caller owns; suppressions say what is owed. A
no-restylecontract ineslint.config.mjsopens a category for one component because the caller legitimately owns it:Label,Description,DialogTitleandDialogDescriptiontake the caller's typography, andSkeletontakes the silhouette and footprint of the content it stands in for. Color stays with the theme in every case. Widen a contract when a whole category belongs to callers; do not widen one to clear a single call site. - The existing backlog is recorded, not exempted.
eslint-suppressions.jsonholds the violations the tree carried when the rules landed, as a per-file, per-rule count. Adding a violation to a file reports every violation of that rule in it, so raising a file's count is a visible diff in that file, review it like any other change, and expect a raise to be justified by what the diff does. Strengthening a rule is the one case where counts rise in files nobody edited: when a rule starts seeing a class it could not classify before, the violations it reports are the tree's existing styling, and recording them is the same backlog arriving later. Say which change did that and keep the two apart in review.npm run lint:design:prunedrops entries whose violations are gone (do this after fixing some);npm run lint:design:suppressre-records the design rules and then prunes, which is what a file move needs, since suppressions are keyed by path, the re-record adds the new path and only the prune removes the old one. It re-baselines everything underclient/srcandpackages/client/src, so for a single move prefer a scoped re-record of just that file: the same six--suppress-ruleflagslint:design:suppresspasses (shadcn/no-restyle,no-raw-colors,no-arbitrary-values,no-inline-styles,require-static-classes,no-unknown-classes) with<new/path.tsx>in place of the directories, since a moved file usually carries entries for more than one rule, followed bynpm run lint:design:prune;npm run lint:design:suppress -- <file>does not scope, because npm appends the argument to the script's own directory arguments. Neither command changes which rules run; both only rewrite the recorded counts. The re-record's own exit status is deliberately ignored: it lints the roots under every rule, those roots carry a pre-existing error backlog, and the baseline is written before ESLint reports it — solint:design:suppressrunslint:design:recordinside|| node -e ""(trueis not a command undercmd.exe, where npm runs scripts on Windows) and lets the prune be the step that can fail. Expect the same when running a scoped re-record by hand, and build the primitives first:shadcn/no-restylereads each variant out ofpackages/client/dist, so a missing or stale bundle records counts that describe a library nobody is compiling against.lint,lint:fix,lint:design:recordandlint:design:pruneeach runnpm run build:client-packagebefore they lint, which is whylint:design:suppressno longer builds on its own account; a bareeslint --suppress-rule ...does not, so run that build ahead of it. - The ratchet is on the count, and on what the count stands for. ESLint compares a file's
current violation count for a rule against the recorded one and suppresses when it is not higher,
so replacing one suppressed violation with a different violation of the same rule in the same
file keeps the count equal and ESLint reports nothing. The backlog is a budget per file, but it is
not a budget you may respend: for every file a diff touches, the runner lints that file's version
at the merge base and reports a design-rule message the head has that the base did not, beyond
whatever that entry's count grew by. So a swap arrives as a failure naming the new violation, a
violation that merely moved does not, adding one with the count raised to cover it is the
documented
npm run lint:design:suppresspath and stays green — the raised count is the line a reviewer reads — and a file the change adds brings no allowance with it, while a renamed one keeps what its violations came with. Two kinds of swap still pass: one whose diagnostic message is the same as the message it replaced, because some rules name the property and not the value (Inline style sets display.is one message fornoneand forflex), and one caused by the diff's own change to a primitive or to the config, because both versions are linted under the head's design inputs.npm run static-checksand the Static Checks lane also validate the baseline itself (shape, positive counts, rules the plugin defines, paths that still exist, paths a design-rule lint actually reports on, and counts that match the file's violations). - The design rules read JSX, not CSS. They are AST rules over
className,cvaandstylein{ts,tsx,js,jsx}, so a.cssfile under either root —client/src/style.css,packages/client/src/components/Field.css— is outside every one of them, and so is the changed-file runner's selection. A raw hex in a stylesheet is caught by review, not bynpm run lint. The theme tokens are the exception: they live in CSS and carry their own check.
Data Management
- Feature hooks:
client/src/data-provider/[Feature]/queries.ts→[Feature]/index.ts→client/src/data-provider/index.ts. - React Query (
@tanstack/react-query) for all API interactions; proper query invalidation on mutations. - QueryKeys and MutationKeys in
packages/data-provider/src/keys.ts.
Client State Ownership
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, with all of their consumers, and keep them inside the feature.
client/src/store/jotai-utils.tscarries 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~/storefor these; accept them 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 state a feature actually owns instead of dragging the global migration forward early.
Data-Provider Integration
- Endpoints:
packages/data-provider/src/api-endpoints.ts - Data service:
packages/data-provider/src/data-service.ts - Types:
packages/data-provider/src/types/queries.ts - Use
encodeURIComponentfor dynamic URL parameters.
Performance
- Prioritize memory and speed efficiency at scale.
- Cursor pagination for large datasets.
- Proper dependency arrays to avoid unnecessary re-renders.
- Leverage React Query caching and background refetching.
Backend Rules (api/**, packages/api/**)
Auth cache invalidation
When adding or changing code that mutates user documents, invalidate the auth user document cache
for the affected users. This covers single-user updates as well as bulk role and user mutations.
Without it, OpenID JWT request burst caching can serve a stale req.user until its TTL expires.
Development Commands
| Command | Purpose |
|---|---|
npm run smart-reinstall |
Install deps (if lockfile changed) + build via Turborepo |
npm run reinstall |
Clean install — wipe node_modules and reinstall from scratch |
npm run backend |
Start the backend server |
npm run backend:dev |
Start backend with file watching (development) |
npm run build |
Build all compiled code via Turborepo (parallel, cached) |
npm run frontend |
Build all compiled code sequentially (legacy fallback) |
npm run frontend:dev |
Start frontend dev server with HMR (port 3090, requires backend running) |
npm run build:data-provider |
Rebuild packages/data-provider after changes |
npm run lint:design:prune |
Drop eslint-suppressions.json entries whose violations are fixed |
npm run lint:design:suppress |
Re-record the design-rule backlog, then prune (needed after a file move) |
- Node.js: v24.16.0
- Database: MongoDB
- Backend runs on
http://localhost:3080/; frontend dev server onhttp://localhost:3090/
Testing
- Framework: Jest, run per-workspace.
- Run tests from their workspace directory:
cd api && npx jest <pattern>,cd packages/api && npx jest <pattern>, etc. - Frontend tests:
__tests__directories alongside components; usetest/layout-test-utilsfor rendering. - Cover loading, success, and error states for UI/data flows.
Typechecking
- A green build is not a typecheck.
packages/api,packages/clientandpackages/data-schemasbuild withtsdownalone, which emits without checking types. Onlypackages/data-providerrunstscas part of its build. - Run
npx tsc --noEmitin the workspace you changed before calling it done.clientalso exposes it asnpm run typecheck. packages/client/tsconfig.jsonexcludes*.spec.ts(x)and*.test.ts(x), so test files there are never typechecked — a type error in a spec surfaces only when the test runs.npm run static-checksruns the Static Checks CI job locally against your staged files;npm run static-checks -- --against origin/devreproduces what CI sees for a pull request, andnpm run static-checks:fulladds the slow gates (TypeScript, config migration tests, unused i18n keys, unused npm packages).
Philosophy
- Real logic over mocks. Exercise actual code paths with real dependencies. Mocking is a last resort.
- Spies over mocks. Assert that real functions are called with expected arguments and frequency without replacing underlying logic.
- MongoDB: use
mongodb-memory-serverfor a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls. - MCP: use real
@modelcontextprotocol/sdkexports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals. - Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls.
- Heavy mocking is a code smell, not a testing strategy.
Formatting
Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors must be resolved.
npm run sort-imports with no arguments rewrites every file under api/, client/src and the four
packages/*/src roots — far beyond what you touched. Always pass explicit paths:
npm run sort-imports -- path/to/file.ts.