LibreChat/packages/data-schemas
Marco Beretta 27f78bc3c7 🎨 feat: Pick the Deployment Theme in librechat.yaml (#16286)
* feat: pick the deployment theme in librechat.yaml

Add `interface.theme` to the config schema, accepting a bundled theme name
or an inline theme definition. The interface loader passes it through, the
pre-login config payload carries it so the login page paints it, and a
DeploymentTheme wrapper around ThemeProvider resolves and validates it and
applies it without persisting it over the user's stored theme.

* fix: restore the user theme when the deployment theme is withdrawn

Move the pre-login interface selection out of the /api route into
buildPreLoginInterface in packages/api, so the route only wires it up.

When an authenticated config drops interface.theme (a principal override
tombstoning it), hand ThemeProvider the user's stored theme instead of
clearing to the LibreChat palette. The e2e scenarios now cover inline and
invalid themes, the withdrawn case, and high-contrast precedence.

* fix: read a legacy stored theme behind a corrupt stored definition

* perf: rebind the deployment theme observer on a cache add, not every event

useIsFetching recomputed the fetch count across every query on each cache
event, which slowed streamed renders enough to break the highlight-throttle
scenario. Subscribe to the query cache and re-render only when a startup
config query is rebuilt.

* test: wait for the composer after sign-in so mobile runs pass

* fix: keep deployment themes whole and restore legacy themes as legacy

A principal override with an inline theme merged into the base theme,
keeping the base's other mode, brands and tokens; interfaceConfig.theme
now replaces whole during override merging.

A withdrawn deployment theme restored a legacy-source stored theme as a
versioned definition, dropping its colors in dark mode; it now goes back
through ThemeProvider's legacy color path.

* fix: persist the user's theme changes after the deployment theme is withdrawn

Persistence now stays off only while a deployment theme is applied and for
the render that restores the stored theme, so later changes through the
theme API are saved again.

* refactor: derive deployment theme persistence from the current theme

(cherry picked from commit f0cbc9a3c0)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16286
2026-10-01 03:46:17 +00:00
..
misc 🍃 fix: Serialize Index Builds and the Agent Edge Cleanup for DocumentDB (#15670) 2026-09-06 15:02:43 -04:00
src 🎨 feat: Pick the Deployment Theme in librechat.yaml (#16286) 2026-10-01 03:46:17 +00:00
.gitignore
babel.config.cjs
jest.config.mjs 🧵 ci: Keep a Floor of Two Jest Workers in CI (#15819) 2026-09-14 00:32:20 -04:00
jest.globalSetup.mjs ⏱️ feat: Run Scheduled Chats Through Durable Agent Triggers (#14939) 2026-08-20 11:51:30 -04:00
LICENSE
package.json 🎁 chore: Bump Packages and Helm After Security Fixes (#16582) 2026-09-30 22:35:22 -04:00
README.md
tsconfig.build.json
tsconfig.json
tsconfig.spec.json
tsdown.config.mjs 🧩 fix: Normalize MCP UI Resource Rendering (#14868) 2026-08-15 12:49:59 -04:00

LibreChat Data Schemas Package

This package provides the database schemas, models, types, and methods for LibreChat using Mongoose ODM.

📁 Package Structure

packages/data-schemas/
├── src/
│   ├── schema/         # Mongoose schema definitions
│   ├── models/         # Model factory functions
│   ├── types/          # TypeScript type definitions
│   ├── methods/        # Database operation methods
│   ├── common/         # Shared constants and enums
│   ├── config/         # Configuration files (winston, etc.)
│   └── index.ts        # Main package exports

🏗️ Architecture Patterns

1. Schema Files (src/schema/)

Schema files define the Mongoose schema structure. They follow these conventions:

  • Naming: Use lowercase filenames (e.g., user.ts, accessRole.ts)
  • Imports: Import types from ~/types for TypeScript support
  • Exports: Export only the schema as default

Example:

import { Schema } from 'mongoose';
import type { IUser } from '~/types';

const userSchema = new Schema<IUser>(
  {
    name: { type: String },
    email: { type: String, required: true },
    // ... other fields
  },
  { timestamps: true }
);

export default userSchema;

2. Type Definitions (src/types/)

Type files define TypeScript interfaces and types. They follow these conventions:

  • Base Type: Define a plain type without Mongoose Document properties
  • Document Interface: Extend the base type with Document and _id
  • Enums/Constants: Place related enums in the type file or common/ if shared

Example:

import type { Document, Types } from 'mongoose';

export type User = {
  name?: string;
  email: string;
  // ... other fields
};

export type IUser = User &
  Document & {
    _id: Types.ObjectId;
  };

3. Model Factory Functions (src/models/)

Model files create Mongoose models using factory functions. They follow these conventions:

  • Function Name: create[EntityName]Model
  • Singleton Pattern: Check if model exists before creating
  • Type Safety: Use the corresponding interface from types

Example:

import userSchema from '~/schema/user';
import type * as t from '~/types';

export function createUserModel(mongoose: typeof import('mongoose')) {
  return mongoose.models.User || mongoose.model<t.IUser>('User', userSchema);
}

4. Database Methods (src/methods/)

Method files contain database operations for each entity. They follow these conventions:

  • Function Name: create[EntityName]Methods
  • Return Type: Export a type for the methods object
  • Operations: Include CRUD operations and entity-specific queries

Example:

import type { Model } from 'mongoose';
import type { IUser } from '~/types';

export function createUserMethods(mongoose: typeof import('mongoose')) {
  async function findUserById(userId: string): Promise<IUser | null> {
    const User = mongoose.models.User as Model<IUser>;
    return await User.findById(userId).lean();
  }

  async function createUser(userData: Partial<IUser>): Promise<IUser> {
    const User = mongoose.models.User as Model<IUser>;
    return await User.create(userData);
  }

  return {
    findUserById,
    createUser,
    // ... other methods
  };
}

export type UserMethods = ReturnType<typeof createUserMethods>;

5. Main Exports (src/index.ts)

The main index file exports:

  • createModels() - Factory function for all models
  • createMethods() - Factory function for all methods
  • Type exports from ~/types
  • Shared utilities and constants

🚀 Adding a New Entity

To add a new entity to the data-schemas package, follow these steps:

Step 1: Create the Type Definition

Create src/types/[entityName].ts:

import type { Document, Types } from 'mongoose';

export type EntityName = {
  /** Field description */
  fieldName: string;
  // ... other fields
};

export type IEntityName = EntityName &
  Document & {
    _id: Types.ObjectId;
  };

Step 2: Update Types Index

Add to src/types/index.ts:

export * from './entityName';

Step 3: Create the Schema

Create src/schema/[entityName].ts:

import { Schema } from 'mongoose';
import type { IEntityName } from '~/types';

const entityNameSchema = new Schema<IEntityName>(
  {
    fieldName: { type: String, required: true },
    // ... other fields
  },
  { timestamps: true }
);

export default entityNameSchema;

Step 4: Create the Model Factory

Create src/models/[entityName].ts:

import entityNameSchema from '~/schema/entityName';
import type * as t from '~/types';

export function createEntityNameModel(mongoose: typeof import('mongoose')) {
  return (
    mongoose.models.EntityName || 
    mongoose.model<t.IEntityName>('EntityName', entityNameSchema)
  );
}

Step 5: Update Models Index

Add to src/models/index.ts:

  1. Import the factory function:
import { createEntityNameModel } from './entityName';
  1. Add to the return object in createModels():
EntityName: createEntityNameModel(mongoose),

Step 6: Create Database Methods

Create src/methods/[entityName].ts:

import type { Model, Types } from 'mongoose';
import type { IEntityName } from '~/types';

export function createEntityNameMethods(mongoose: typeof import('mongoose')) {
  async function findEntityById(id: string | Types.ObjectId): Promise<IEntityName | null> {
    const EntityName = mongoose.models.EntityName as Model<IEntityName>;
    return await EntityName.findById(id).lean();
  }

  // ... other methods

  return {
    findEntityById,
    // ... other methods
  };
}

export type EntityNameMethods = ReturnType<typeof createEntityNameMethods>;

Step 7: Update Methods Index

Add to src/methods/index.ts:

  1. Import the methods:
import { createEntityNameMethods, type EntityNameMethods } from './entityName';
  1. Add to the return object in createMethods():
...createEntityNameMethods(mongoose),
  1. Add to the AllMethods type:
export type AllMethods = UserMethods &
  // ... other methods
  EntityNameMethods;

📝 Best Practices

  1. Consistent Naming: Use lowercase for filenames, PascalCase for types/interfaces
  2. Type Safety: Always use TypeScript types, avoid any
  3. JSDoc Comments: Document complex fields and methods
  4. Indexes: Define database indexes in schema files for query performance
  5. Validation: Use Mongoose schema validation for data integrity
  6. Lean Queries: Use .lean() for read operations when you don't need Mongoose document methods

🔧 Common Patterns

Enums and Constants

Place shared enums in src/common/:

// src/common/permissions.ts
export enum PermissionBits {
  VIEW = 1,
  EDIT = 2,
  DELETE = 4,
  SHARE = 8,
}

Compound Indexes

For complex queries, add compound indexes:

schema.index({ field1: 1, field2: 1 });
schema.index(
  { uniqueField: 1 },
  { 
    unique: true, 
    partialFilterExpression: { uniqueField: { $exists: true } }
  }
);

Virtual Properties

Add computed properties using virtuals:

schema.virtual('fullName').get(function() {
  return `${this.firstName} ${this.lastName}`;
});

🧪 Testing

When adding new entities, ensure:

  • Types compile without errors
  • Models can be created successfully
  • Methods handle edge cases (null checks, validation)
  • Indexes are properly defined for query patterns

📚 Resources