Skip to content

Getting Started for Contributors

Important:

Requirements

  1. ✅ Git - Essential
  2. ✅ Node.js - Essential , use the LTS version
  3. ✅ Git LFS - Useful for uploading files with larger sizes.
  4. ✅ Github Desktop - Optional
  5. ✨ VSCode - Recommended Source-code Editor
  6. 🐳 Docker Desktop - Recommended (more on that later)

It is recommended to install the following extensions in VS Code:

Prepare the Environment

npm vs Docker

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:

  • 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.

For these reasons, while Docker remains the recommended installation method for production and distribution due to its containerization benefits, npm is the preferred choice for development within the LibreChat ecosystem.

GitHub

Screenshots:

image image image

  • Download your new branch on your local pc
Download your LibreChat branch 
git clone -b branch-name https://github.com/username/LibreChat.git

note:

replace branch-name and username with your own

Open it in VS Code

  • Once you successfully cloned your branch
  • Navigate to the LibreChat folder: 
    cd LibreChat
  • Open it in VS Code: 
    code .

Prepare LibreChat

  • Open the terminal in vscode with Ctrl + Shift + `

    • Alternatively you can use Ctrl + J to open the bottom pane and select the terminal from there

  • Install the LibreChat depencencies

    • npm ci
    • npm run frontend
  • .env Configuration
    • Create the .env file. If you dont have one handy, you can duplicate the .env.example file and configure it.

.env

The default values in the example file should be fine, except for MONGO_URI . You will need to provide your own. You can use MongoDB Community Server , MongoDB Atlas Cloud , see this doc to setup Mongodb Atlas Cloud: Online MongoDB .

You can also enable verbose server output in the console with DEBUG_CONSOLE set to true.

Development Workflow

To efficiently work on LibreChat, use the following commands:

  • Starting the Backend:

    • Use npm run backend to start LibreChat normally.
    • For active development, npm run backend:dev will monitor backend changes.
    • Access the running application at http://localhost:3080/ .

  • Running the Frontend in Development Mode:

    • ❗ Ensure the backend is also running.
    • Execute npm run frontend:dev to actively monitor frontend changes.
    • View the frontend in development mode at http://localhost:3090/ .

Pro Tip:

To avoid the hassle of restarting both frontend and backend during frontend development, simply run npm run frontend:dev for real-time updates on port 3090.

Perform Tests Locally

Before submitting your updates, it’s crucial to verify they pass all tests. Follow these steps to run tests locally, see: Perform Tests Locally

By running these tests, you can ensure your contributions are robust and ready for integration.

Commit, Push, Pull Request (PR)

Make a Commit

Commits should be made when you reach a logical checkpoint in your development process. This could be after a new feature is added, a bug is fixed, or a set of related changes is completed. Each commit should contain a clear message that explains what changes have been made and why.

Example: 

git add .
git commit -m "Add login functionality"

Push Changes

You should push your changes to the remote repository after a series of commits that complete a feature or fix a known issue. Pushing often helps to ensure that your changes are safely stored remotely and makes collaboration with others easier.

Example: 

git push origin feature-branch-name

Make a Pull Request (PR)

A Pull Request should be made when you want to merge your changes from a feature branch into the main branch. Before creating a PR, make sure to:

  1. Pull the latest changes from the main branch and resolve any conflicts.
  2. Push your updated feature branch.
  3. Ensure your code adheres to the project's style and contribution guidelines.

Example: 

git checkout main
git pull origin main
git checkout feature-branch-name
git merge main
# Resolve conflicts if any
git push origin feature-branch-name
# Now go to GitHub and open a pull request
When you are ready, open your repository in a browser and click on "Contribute" image

Note:

Remember to provide a detailed description in your PR that explains the changes and the value they add to the project. It's also good practice to reference any related issues.

Tip

You can use GitHub Desktop to monitor what you've changed. image

Warning

If git commit fails due to ESLint errors, read the error message and understand what's wrong. It could be an unused variable or other issues.

Reverting Commits Safely

If you need to undo changes in your feature branch, proceed with caution. This guide is for situations where you have commits that need to be removed and there are no open Pull Requests (PRs) or ongoing work on the branch.

Warning

Force pushing can rewrite history and potentially disrupt the workflow for others. Use this method only as a last resort.

  1. Update your local repository with the latest changes from the feature branch: 
    git pull origin feature-branch-name
  2. Review the commit history to determine how many commits to revert: 
    git log

  3. Start an interactive rebase session for the last N commits you wish to revert: 

    git rebase -i HEAD~N
    Replace N with the number of commits you want to go back, such as 2 for two commits or 100 for a hundred.

  4. In the interactive editor, replace pick with drop for the commits you want to remove. Then save and exit the editor (usually with Esc followed by typing :wq ).

  5. Force push the changes to the remote repository: 

    git push --force origin feature-branch-name