📗 docs: Refresh Node 24 Development Guidance

content/docs/development/architecture.mdx

@@ -12,7 +12,7 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries:
 |---|---|---|---|---|
 | `/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 |
+| `/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 |
@@ -29,15 +29,16 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries:
 | 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 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: v20.19.0+ or ^22.12.0 or >= 23.0.0
+- Node.js: `v24.16.0`
+- npm: `v11.16.0`
 - Database: MongoDB
 - Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/`
 

content/docs/development/conventions.mdx

@@ -12,7 +12,7 @@ LibreChat is a monorepo. All new code should target the correct workspace:
 |---|---|---|---|
 | `/api` | JS (legacy) | Backend | Express server — minimize changes here |
 | `/packages/api` | **TypeScript** | Backend | New backend code lives here (TS only, consumed by `/api`) |
-| `/packages/data-schemas` | TypeScript | Backend | Database models/schemas |
+| `/packages/data-schemas` | TypeScript | Backend | Database models/schemas and database-specific shared logic |
 | `/packages/data-provider` | TypeScript | Shared | API types, endpoints, data-service — used by frontend and backend |
 | `/client` | TypeScript/React | Frontend | Frontend SPA |
 | `/packages/client` | TypeScript | Frontend | Shared frontend utilities |
@@ -22,6 +22,7 @@ LibreChat is a monorepo. All new code should target the correct workspace:
 - Database-specific shared logic goes in `/packages/data-schemas`.
 - Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`.
 - Build all compiled code from project root: `npm run build`.
+- Rebuild shared data-provider code after API/type changes: `npm run build:data-provider`.
 
 ---
 
@@ -33,12 +34,22 @@ LibreChat is a monorepo. All new code should target the correct workspace:
 - Use the provided `.eslintrc` and `.prettierrc` files for consistent code formatting.
 - Fix all formatting lint errors using auto-fix when available. All TypeScript/ESLint warnings and errors must be resolved.
 
+### Naming and File Organization
+
+- Use single-word file names whenever possible, such as `permissions.ts`, `capabilities.ts`,
+  or `service.ts`.
+- When multiple words are needed, prefer a single-word directory that gives the file context, such
+  as `admin/capabilities.ts` instead of `adminCapabilities.ts`.
+- Let the directory provide context. Prefer `app/service.ts` over `app/appConfigService.ts`.
+
 ### Code Structure
 
 - **Never-nesting**: use early returns, flat code, minimal indentation. Break complex operations into well-named helpers.
 - **Functional first**: pure functions, immutable data, `map`/`filter`/`reduce` over imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation.
 - **No dynamic imports** unless absolutely necessary.
-- Extract repeated logic into dedicated utility functions (DRY).
+- Extract repeated logic into dedicated utility functions (DRY). Prefer parameterized helpers,
+  constants, shared validators, centralized error handling, and shared types over near-duplicate
+  implementations.
 
 ### Iteration and Performance
 
@@ -196,3 +207,8 @@ When adding shared API integration, update:
 - Run tests from their workspace directory: `cd api && npx jest <pattern>`, `cd packages/api && npx jest <pattern>`, etc.
 - Cover loading, success, and error states for UI/data flows.
 - Use `test/layout-test-utils` for rendering components in frontend tests.
+- Prefer real logic over mocks. Mock only what cannot be controlled locally, such as external HTTP
+  APIs, rate-limited services, and non-deterministic system calls.
+- Use spies when you need to assert calls without replacing the underlying implementation.
+- Use `mongodb-memory-server` for MongoDB-backed tests so queries and schema validation exercise
+  real database behavior.

content/docs/development/get_started.mdx

@@ -7,7 +7,8 @@ description: Learn how to contribute using GitHub Desktop, VS Code extensions, a
 ## Requirements
 
 - [Git](https://git-scm.com/downloads) (Essential)
-- [Node.js](https://nodejs.org/en/download) (Essential, use v20.19.0+ or ^22.12.0 or >= 23.0.0)
+- [Node.js](https://nodejs.org/en/download) `v24.16.0` (Essential)
+- npm `v11.16.0` (Essential)
 - [MongoDB](https://www.mongodb.com/try/download/community) (Essential, for the database)
 - [Git LFS](https://git-lfs.com/) (Useful for larger files)
 - [GitHub Desktop](https://desktop.github.com/) (Optional)
@@ -23,6 +24,28 @@ Install these extensions in VS Code:
 
 ## Prepare the Environment
 
+### Node.js and npm
+
+If you use `nvm`, install and select the recommended Node.js version before installing LibreChat:
+
+```sh filename="Use Node.js 24"
+nvm install 24.16.0
+nvm use 24.16.0
+npm install -g npm@11.16.0
+```
+
+Verify your shell is using the expected versions:
+
+```sh filename="Check Node.js and npm"
+node -v
+npm -v
+```
+
+```txt filename="Expected versions"
+v24.16.0
+11.16.0
+```
+
 ### GitHub
 
 - Fork the LibreChat repository: [https://github.com/danny-avila/LibreChat/fork](https://github.com/danny-avila/LibreChat/fork)
@@ -57,7 +80,7 @@ git clone -b branch-name https://github.com/username/LibreChat.git
   npm run smart-reinstall
   ```
 
-  > Alternatively, use `npm ci` for a fresh lockfile-based install.
+  > If you just changed Node.js or npm versions, use `npm run reinstall` once for a clean install.
 
 - ```sh filename="Build all compiled code"
   npm run build
@@ -68,31 +91,28 @@ git clone -b branch-name https://github.com/username/LibreChat.git
 
 <Callout type="warning" title="Warning">
   The default values in `.env.example` are usually fine, except for `MONGO_URI`. Provide your own.
-  Make sure to install MongoDB and configure `MONGO_URI` correctly to connect to your MongoDB instance.
-  Use [MongoDB Community Server](https://www.mongodb.com/try/download/community) or [MongoDB Atlas
-  Cloud](https://www.mongodb.com/cloud/atlas/register).
+  Make sure to install MongoDB and configure `MONGO_URI` correctly to connect to your MongoDB
+  instance. Use [MongoDB Community Server](https://www.mongodb.com/try/download/community) or
+  [MongoDB Atlas Cloud](https://www.mongodb.com/cloud/atlas/register).
 </Callout>
 
 ### Development Workflow
 
 For efficient work on LibreChat, use these commands:
 
 - **Starting Backend:**
-
   - Use `npm run backend` for normal operation.
   - For active development, use `npm run backend:dev` to monitor changes.
   - Access at `http://localhost:3080/`.
 
 - **Running Frontend in Development Mode:**
-
   - **Ensure backend is running.**
   - Use `npm run frontend:dev` to monitor frontend changes.
   - View at `http://localhost:3090/`.
 
 <Callout type="tip" title="Pro Tips">
-  - For real-time updates during frontend development, run `npm run frontend:dev` to avoid
-  restarting both frontend and backend on port 3090. - Set `DEBUG_CONSOLE` to true in `.env` for
-  verbose server output in the console.
+  - For real-time updates during frontend development, run `npm run frontend:dev` so frontend changes refresh on port `3090`.
+  - Set `DEBUG_CONSOLE=true` in `.env` for verbose server output in the console.
 </Callout>
 
 ## Local Testing
@@ -138,7 +158,7 @@ git push origin feature-branch-name
 git checkout main
 git pull origin main
 git checkout feature-branch-name
-git merge main
+git rebase main
 # Resolve conflicts if any
 git push origin feature-branch-name
 # Open PR on GitHub
@@ -177,5 +197,5 @@ To undo changes in a feature branch, follow these steps cautiously:
   > Replace `pick` with `drop` for commits to remove. Save and exit editor.
 
 - ```bash filename="4. Force push changes to remote repository:"
-  git push --force origin feature-branch-name
+  git push --force-with-lease origin feature-branch-name
   ```

content/docs/development/index.mdx

@@ -1,21 +1,56 @@
 ---
 title: Overview
 icon: BookOpen
-description: LibreChat's introduction to development 
+description: How to set up a productive LibreChat development workflow.
 ---
 
-While Docker is our preferred method for installing LibreChat due to its ease of setting up and consistency across different environments, **we strongly recommend using `npm` for development purposes.** This recommendation is based on several advantages that npm offers for developers:
+Docker is the preferred install path for most users, but local LibreChat development should use
+`npm`. Running the app directly on your machine gives faster feedback, clearer debugging, and direct
+access to the monorepo workspaces without rebuilding containers after each change.
 
-- **Faster Iteration:** npm allows for quicker iteration cycles during development. Changes made to the codebase can be immediately reflected without the need to rebuild the entire Docker image, leading to a more efficient development process.
-- **Direct Dependency Management:** Using npm gives developers direct control over the dependencies. It's easier to install, update, or remove packages, and manage project dependencies in real-time, which is crucial for development.
-- **Simplified Debugging:** Debugging is more straightforward with npm, as developers can directly interact with the code and tools without the abstraction layer that Docker introduces. This direct interaction facilitates easier identification and resolution of issues.
-- **Native Environment:** Developing with npm allows the application to run in its native environment on your machine. This can help in catching environment-specific issues early in the development cycle.
+## Recommended Toolchain
 
-<Callout type="info" title="Dev Ressources" emoji="🧑‍💻">
-  - 📚 If you're new to concepts like **repositories**, **pull requests (PRs)**, **forks**, and **branches**, start with the official GitHub documentation: 
-    - **[Getting Started - About Collaborative Development Models](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)**
-  - 👥 Our contributor guidelines can be found at: 
-    - **[Contributor Guidelines](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md)** 
-  - 💻 To learn more about our coding standards see: 
-    - **[Coding Conventions](/docs/development/conventions)**
+Use this toolchain for npm-based development:
+
+| Tool    | Version                   |
+| ------- | ------------------------- |
+| Node.js | `v24.16.0`                |
+| npm     | `v11.16.0`                |
+| MongoDB | Atlas or Community Server |
+
+Node 24 satisfies LibreChat's runtime needs for CommonJS interop with ESM-only packages, WebCrypto,
+and the Fetch API. If your shell still reports an older Node version, run `nvm use 24.16.0` from the
+LibreChat repository before installing dependencies.
+
+## Work In The Right Workspace
+
+LibreChat is a monorepo. Pick the smallest workspace that owns the behavior you are changing:
+
+| Workspace                 | Use it for                                                            |
+| ------------------------- | --------------------------------------------------------------------- |
+| `/packages/api`           | New backend TypeScript services, controllers, and shared server logic |
+| `/api`                    | Legacy Express server integration; keep changes thin                  |
+| `/packages/data-schemas`  | Database models, schemas, and database-specific shared logic          |
+| `/packages/data-provider` | Shared API types, endpoints, query keys, and data-service functions   |
+| `/client`                 | React application code                                                |
+| `/packages/client`        | Shared frontend utilities                                             |
+
+## Daily Commands
+
+| Command                       | Purpose                                                                            |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `npm run smart-reinstall`     | Install dependencies when needed and build compiled workspaces                     |
+| `npm run reinstall`           | Clean install after changing Node/npm versions or when dependency state is suspect |
+| `npm run backend:dev`         | Start the backend with file watching                                               |
+| `npm run frontend:dev`        | Start the frontend dev server on port `3090`                                       |
+| `npm run build:data-provider` | Rebuild shared data-provider code after API/type changes                           |
+| `npm run build`               | Build all compiled workspaces through Turborepo                                    |
+
+## Development Resources
+
+<Callout type="info" title="Development Resources">
+  - If you are new to repositories, forks, branches, and pull requests, start with **[GitHub's collaborative development guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)**.
+  - Read the **[Contributor Guidelines](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md)** before opening a PR.
+  - Use **[Contributor Setup](/docs/development/get_started)** for the full local setup flow.
+  - Use **[Code Standards and Conventions](/docs/development/conventions)** for workspace boundaries, import order, typing, testing, and frontend rules.
 </Callout>

content/docs/development/testing.mdx

@@ -9,13 +9,17 @@ description: How to locally test the app during development.
 Before submitting your updates, verify they pass all unit tests. Follow these steps to run tests locally:
 
 - Copy your `.env.example` file in the `/api` folder and rename it to `.env`
+
   ```bash filename="create a /api/.env file"
   cp .env.example ./api/.env
   ```
 
 - Add `NODE_ENV=CI` to your `/api/.env` file
 - `npm run test:client`
 - `npm run test:api`
+- `npm run test:packages:api`
+- `npm run test:packages:data-provider`
+- `npm run test:packages:data-schemas`
 
 ### Running Tests Per-Workspace
 
@@ -24,9 +28,20 @@ Tests are run using Jest from their respective workspace directories. Target spe
 ```bash
 cd api && npx jest <pattern>
 cd packages/api && npx jest <pattern>
+cd packages/data-provider && npx jest <pattern>
+cd packages/data-schemas && npx jest <pattern>
 cd client && npx jest <pattern>
 ```
 
+## Testing Philosophy
+
+- Prefer real logic over mocks. Mock only what cannot be controlled locally, such as external HTTP
+  APIs, rate-limited services, and non-deterministic system calls.
+- Use spies when you need to assert that real functions were called with expected arguments.
+- Use `mongodb-memory-server` for MongoDB-backed tests so queries and schema validation run against
+  real database behavior.
+- Cover loading, success, and error states for UI/data flows.
+
 <Callout type="tip" title="Tip">
-  Use `test/layout-test-utils` for rendering components in frontend tests. Cover loading, success, and error states for UI/data flows.
+  Use `test/layout-test-utils` for rendering components in frontend tests.
 </Callout>

content/docs/features/image_gen.mdx

@@ -363,7 +363,7 @@ mcpServers:
     args:
       - "{REPLACE_WITH_NODE_MODULES_LOCATION}/@gongrzhe/image-gen-server/build/index.js"
       # Example with output from `npm root -g`:
-      # - "/home/danny/.nvm/versions/node/v20.19.0/lib/node_modules/@gongrzhe/image-gen-server/build/index.js"
+      # - "/home/danny/.nvm/versions/node/v24.16.0/lib/node_modules/@gongrzhe/image-gen-server/build/index.js"
     env:
       # Do not hardcode the API token here, use the environment variable instead
       # The following will pick up the token from your .env file or environment

content/docs/local/npm.mdx

@@ -8,13 +8,28 @@ For most scenarios, Docker Compose is the recommended installation method due to
 
 ## Prerequisites
 
-- Node.js v20.19.0+ (or ^22.12.0 or >= 23.0.0): [https://nodejs.org/en/download](https://nodejs.org/en/download)
-  - LibreChat uses CommonJS (CJS) and requires these specific Node.js versions for compatibility with openid-client v6
+- Node.js `v24.16.0`: [https://nodejs.org/en/download](https://nodejs.org/en/download)
+- npm `v11.16.0`
+  - LibreChat uses CommonJS (CJS) and openid-client v6; Node 24 satisfies the required CJS/ESM
+    interop, WebCrypto, and Fetch API runtime support.
 - Git: https://git-scm.com/download/
 - MongoDB (Atlas or Community Server)
   - [MongoDB Atlas](/docs/configuration/mongodb/mongodb_atlas)
   - [MongoDB Community Server](/docs/configuration/mongodb/mongodb_community)
 
+If you use `nvm`, install and select the recommended Node.js version, then update npm:
+
+```bash filename="Use Node.js 24 and npm 11"
+nvm install 24.16.0
+nvm use 24.16.0
+npm install -g npm@11.16.0
+node -v
+npm -v
+```
+
+You should see `v24.16.0` for Node.js and `11.16.0` for npm before installing LibreChat
+dependencies.
+
 ## Installation Steps
 
 ### Preparation
@@ -48,12 +63,11 @@ Important: Edit the newly created `.env` file to update the `MONGO_URI` with you
 Once you've completed the preparation steps, run the following commands:
 
 ```bash filename="Install dependencies"
-npm ci
+npm run reinstall
 ```
 
-```bash filename="Build the Frontend"
-npm run frontend
-```
+`npm run reinstall` performs a clean dependency install and builds LibreChat. Use it after changing
+Node.js or npm versions so native packages are rebuilt against the active runtime.
 
 ```bash filename="Start LibreChat!"
 npm run backend
@@ -80,12 +94,10 @@ git pull
 ```
 
 ```bash filename="Update dependencies"
-npm ci
+npm run smart-reinstall
 ```
 
-```bash filename="Rebuild the Frontend"
-npm run frontend
-```
+If you changed Node.js or npm versions during the update, run `npm run reinstall` instead.
 
 ```bash filename="Start LibreChat!"
 npm run backend
@@ -106,4 +118,4 @@ This will enable you to customize your LibreChat experience with optional featur
 **see also:**
 - [User Authentication System Setup](/docs/configuration/authentication)
 - [AI Setup](/docs/configuration/pre_configured_ai)
-- [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml)
+- [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml)