# Contributor Setup (/docs/development/get_started)

## Requirements

- [Git](https://git-scm.com/downloads) (Essential)
- [Node.js](https://nodejs.org/en/download) (Essential, use v20.19.0+ or ^22.12.0 or >= 23.0.0)
- [MongoDB](https://www.mongodb.com/try/download/community) (Essential, for the database)
- [Git LFS](https://git-lfs.com/) (Useful for larger files)
- [GitHub Desktop](https://desktop.github.com/) (Optional)
- [VSCode](https://code.visualstudio.com/Download) (Recommended Source-code Editor)

### Recommended VSCode Extensions

Install these extensions in VS Code:

- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)

## Prepare the Environment

### GitHub

- Fork the LibreChat repository: [https://github.com/danny-avila/LibreChat/fork](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

```sh filename="Download your LibreChat branch"
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:
  ```sh filename="Navigate to LibreChat folder"
  cd LibreChat
  ```
  ```sh filename="Open in VS Code"
  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.

- ```sh filename="Install LibreChat dependencies"
  npm run smart-reinstall
  ```

  > Alternatively, use `npm ci` for a fresh lockfile-based install.

- ```sh filename="Build all compiled code"
  npm run build
  ```

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

<Callout type="warning" title="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](https://www.mongodb.com/try/download/community) or [MongoDB Atlas
  Cloud](https://www.mongodb.com/cloud/atlas/register).
</Callout>

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

<Callout type="tip" title="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.
</Callout>

## Local Testing

Before submission, test your updates locally, see: [Perform Tests Locally](/docs/development/testing)

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:**

```bash filename=" "
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:**

```bash filename=" "
git push origin feature-branch-name
```

### Create a Pull Request (PR)

**Pull Request** merges changes from a feature branch into the main branch.

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

**Example:**

```bash filename=" "
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".

<Callout type="info" title="Note:">
  Provide a detailed PR description explaining changes and their value. Reference related issues.
</Callout>

<Callout type="tip" title="Tip">
  Use GitHub Desktop to track changes.
</Callout>

<Callout type="warning" title="Warning">
  If `git commit` fails due to ESLint errors, understand and fix the issue.
</Callout>

## Revert Commits Safely

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

- ```bash filename="1. Update local repository from feature branch:"
  git pull origin feature-branch-name
  ```

- ```bash filename="2. Review commit history to determine commits to revert:"
  git log
  ```

- ```bash filename="3. Start an interactive rebase for 'N' commits to revert:"
  git rebase -i HEAD~N
  ```

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

- ```bash filename="4. Force push changes to remote repository:"
  git push --force origin feature-branch-name
  ```