GUIDE: Customising the LibreChat user interface (UI)

[CMorenoStokoe]

Configuring the GUI

Background

Writing a quick post to share some details that are not yet documented. I wanted to edit the user interface, and from some googling it looks like others want to do this as well. There was no comprehensive guide, so I used some previous GitHub issues and reverse-engineered the webapp to make a quick guide on how to do things like changing the colors, logos, layouts etc of the website. You will need some understanding of React, Tailwind, Docker, until these UI options are made more easily editable to developers.
This was inspired by previous issues, which are the top results in Google, but only show that developers could not figure this information out (e.g., #3706, #2300, #4078).

Disclaimer: I am not a LibreChat developer, I am not affiliated with them, I just want to help other developers. This is just how I got this working, it may not be best practice, or has some unforeseen pitfalls, but I am sharing for future developers

Overview

The LibreChat components can be customised and configured by developers. The following files are important for configuring the LibreChat interface. There are two types of changes:

Making supported changes

"Supported changes" largely just require editing a file at the top level and restarting the Docker swarm to enact. These include:

• Environmental variables can be edited in ./.env (e.g., title)
• Configuration file ./librechat.yaml (e.g., custom end-points, and end-point configuration)

Unsupported changes

"Unsupported changes" require editing the source code of the React app itself, re-building the app distribution, and including these files in the Docker image. Most detailed changes are unsupported and involve editing various source files. These are generally contained within the contained within ./client folder, and include:

• Metadata can be edited in index.html (title, favicon)
• Styles can be customised in tailwind.config.cjs & src/style.css (colors, fonts, dark mode)
• Logos and images in public/assets (e.g., the main logo.svg)
• Fonts can be added in public/assets/fonts (use same name to override, or specify in CSS as detailed below)
• Customize UI components in client/src/components/*.tsx (chat box, input, message bubbles)

Customising LibreChat

Supported changes

Some customisation is already supported and requires just editing the top-level ./librechat.yaml file. This includes giving chat endpoints a custom logo, name, default pre-set values, as well as enabling/disabling some UI features (e.g., side-bar, agents, disable model selection to focus on one model such as a custom endpoint).

A specification for the librechat.yaml, including customisable values, can be found in the Documentation.
Note, you will need to perform a docker-override Guide.

These are largely documented in the existing Documentation so won't be the focus of this post.

Unsupported changes to assets e.g., images, icons, fonts

Assets are contained in public/assets/ and can be added to or replaced with new assets. Simply drag and drop new images to this folder.
New and replacement assets will need to be explicitly included in the Docker override file to apply changes. The docker container can then be rebuilt with the npm command docker compose build --no-cache (the --no-cache flag ensures our changes definitely get included).

For example, public assets can be included with the following code:

docker-compose.override.yaml

# Custom config file
services:
# Custom assets
      - type: bind
        source: ./client/public/assets
        target: /app/client/public/assets

For more information see #3706

Unsupported changes to React/HTML components

Changes to React/HTML components might include changing the color scheme of the app, editing the layout of React components, or adding a corporate logo to the top of the page if you are building an internal corporate site.

To apply changes to the GUI the Docker image will need to be re-built, with the new distribution files overrides in the Docker container like with assets above, with the additional step of rebuilding the web app when you make changes, to generate a new distribution.

The web app can be rebuilt from the root folder with the npm command npm run frontend.
The docker container can then be rebuilt with docker compose build --no-cache.

For example, a new distribution, along with the custom assets from the previous step, can be included with the following code:

docker-compose.override.yaml

# Custom config file
services:
   # Custom assets
      - type: bind
        source: ./client/public/assets
        target: /app/client/public/assets
   # Custom web app
      - type: bind
        source: ./client/dist
        target: /app/client/dist

For more information see #2300