Contributor Setup

Learn how to contribute using GitHub Desktop, VS Code extensions, and Git rebase.

Requirements

Git (Essential)
Node.js (Essential, use v20.19.0+ or ^22.12.0 or >= 23.0.0)
MongoDB (Essential, for the database)
Git LFS (Useful for larger files)
GitHub Desktop (Optional)
VSCode (Recommended Source-code Editor)

Prepare the Environment

GitHub

Fork the LibreChat repository: https://github.com/danny-avila/LibreChat/fork
Create a branch on your fork, name it properly, and link it to the original repository.
Download your new branch to your local PC

git clone -b branch-name https://github.com/username/LibreChat.git

Replace branch-name and username with your details

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
Alternatively, use npm ci for a fresh lockfile-based install.
npm run build
.env Configuration
- Create the .env file. If you don't have one, duplicate .env.example and configure it.

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 or MongoDB Atlas Cloud.

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

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.

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. Include clear messages explaining changes.

Example:

git add .
git commit -m "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 main branch.

Pull latest changes from main branch and resolve conflicts.
Push updated feature branch.
Ensure code follows project 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
# Open PR on GitHub

Access your repository in a browser and click "Contribute".

Note:

Provide a detailed PR description explaining changes and their value. Reference related issues.

Tip

Use GitHub Desktop to track changes.

Warning

If git commit fails due to ESLint errors, understand and fix the issue.

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 origin feature-branch-name