LibreChatProject Architecture
Overview of LibreChat's monorepo workspace structure and package boundaries.
Monorepo Structure
LibreChat is organized as a monorepo with clearly defined workspace boundaries:
| 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 |
/packages/chat | TypeScript | Frontend | packages/data-provider, packages/client | @librechat/chat: chat state, transport, and message components moving out of /client; never imports the app |
Key Principles
- All new backend code must be TypeScript in
/packages/api. - Keep
/apichanges to the absolute minimum — thin JS wrappers calling into/packages/api. - Database-specific shared logic belongs in
/packages/data-schemas. - Frontend/backend shared API logic (endpoints, types, data-service) belongs in
/packages/data-provider.
Build and Install
| Command | Purpose |
|---|---|
npm run smart-reinstall | Install deps (if lockfile changed) + build via Turborepo |
npm run reinstall | Clean install after changing Node/npm versions or when dependency state is suspect |
npm run build | Build all compiled code via Turborepo (parallel, cached) |
npm run frontend | Build all compiled code sequentially (legacy fallback) |
npm run build:data-provider | Rebuild packages/data-provider after changes |
npm run backend | Start the backend server |
npm run backend:dev | Start backend with file watching (development) |
npm run frontend:dev | Start frontend dev server with HMR (port 3090, requires backend running) |
- Node.js:
v24.22.1 - npm:
v11.13.0 - Database: MongoDB
- Backend runs on
http://localhost:3080/; frontend dev server onhttp://localhost:3090/
Note
For the full set of coding standards and conventions, see Code Standards and Conventions.
Shared Schema and Component Compatibility
The v0.8.9-rc1 shared packages use Zod 4. Consumers composing librechat-data-provider schemas should use compatible Zod 4 APIs and infer input/output types from the exported schema rather than relying on Zod 3 internals. Rebuild custom package consumers together; forcing Zod 3 through an override is not a compatibility path.
The client package no longer exports the legacy Select, SelectDropDown, Dialog, DialogTemplate, or Radix DropdownMenu controls. Use the maintained Dropdown-based selectors and dialog primitives used by current LibreChat callers. See the upgrade guide.
How is this guide?