Contributor Setup

Requirements

• Git (Essential)
• Node.js v24.22.1 (Essential)
• npm v11.13.0 (Essential)
• MongoDB (Essential, for the database)
• Git LFS (Useful for larger files)
• GitHub Desktop (Optional)
• VSCode (Recommended Source-code Editor)

Recommended VSCode Extensions

Install these extensions in VS Code:

• Prettier
• ESLint
• GitLens

Prepare the Environment

Node.js and npm

If you use nvm, install and select the recommended Node.js version before installing LibreChat:

nvm install 24.22.1
nvm use 24.22.1
npm install -g [email protected]

The .nvmrc file in the LibreChat repository is the source of truth for the Node.js version; running nvm use from the repository root selects it.

Verify your shell is using the expected versions:

node -v
npm -v

v24.22.1
11.13.0

GitHub

• Fork the LibreChat repository: https://github.com/LibreChat-AI/LibreChat/fork

• Clone your fork and add the original repository as upstream. Contributions branch from and target dev; main only moves at release time.

git clone https://github.com/username/LibreChat.git
cd LibreChat
git remote add upstream https://github.com/LibreChat-AI/LibreChat.git
git fetch upstream dev
git checkout -B dev upstream/dev

• Create a descriptive, slash-based branch off dev:

git checkout -b new/feature/x

Replace username and the branch name with your details. Do not use npm run update to refresh a development branch; it is the self-host updater and checks out main.

Open in VS Code

• After cloning your branch:

  cd LibreChat

  code .

Prepare LibreChat

• Open the terminal in VS Code with ctrl+shift+`` ```

  Alternatively, use ctrl+j to open the bottom pane and select the terminal.

• npm run smart-reinstall

  If you just changed Node.js or npm versions, use npm run reinstall once for a clean install.

• npm run build

• .env Configuration

  • Create the .env file. If you don't have one, duplicate .env.example and configure it.

• Git hooks

  • npm install sets up husky pre-commit checks, which run the Static Checks CI job locally on the files in each commit (ESLint, Prettier, import order, circular dependencies). Set HUSKY=0 to opt out, and run the checks by hand with npm run static-checks.

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

Local Testing

Before submission, test your updates locally, see: Perform Tests Locally

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

Commit, Push, Pull Request (PR)

Make a Commit

Commits mark logical checkpoints in development. Use conventional commit messages that begin with a type such as feat, fix, docs, or refactor, followed by a brief summary.

Example:

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

Push Changes

Push changes to the remote repository after completing a feature or fixing an issue.

Example:

git push origin feature-branch-name

Create a Pull Request (PR)

Pull Request merges changes from a feature branch into the dev branch.

1. Pull the latest changes from dev and resolve conflicts.
2. Push updated feature branch.
3. Ensure code follows project guidelines.

Example:

git fetch upstream dev
git checkout feature-branch-name
git rebase upstream/dev
# Resolve conflicts if any
git push origin feature-branch-name
# Open PR on GitHub

Access your fork in a browser and click "Contribute", and make sure the pull request targets dev.

Revert Commits Safely

To undo changes in a feature branch, follow these steps cautiously:

• git pull origin feature-branch-name

• git log

• git rebase -i HEAD~N

  Replace pick with drop for commits to remove. Save and exit editor.

• git push --force-with-lease origin feature-branch-name