Improving the Developer Experience Workflow

[mawburn]

I believe that there is room to improve the developer experience for this repo. I'm not certain if there's a missing document or a detailed guide for everyone's flow, but, starting and running the repo in dev mode can be challenging. This certainly IS NOT a critique on the team or the project itself, but sometimes, these inconveniences happen with time, and it takes fresh eyes to identify things.

Identifying the Issue

Being new to this, my first PR has been a learning curve and gave me some insight into potential improvements. Despite the PR being small and trivial, getting the groundwork established wasn't. It actually took me quite a while between to work and life to get some time to sit down and figure out how to get a local dev environment up.

I set up the dev environment on two different MacOS machines, and the following steps were more or less the same on both. I don't use any other type of machine though, but I understand some of the limitations of other platforms. I admit, I might've overlooked some documented details, but here are the steps I followed:

1. Ran npm install, followed by npm install in api, data-provider, and client folders. Post this, went back to root and again ran npm install. At some point I also ran npm ci to ensure everything was installed properly. There seems to be an insufficient documentation about this particular command, but it appears to perform more or less the same function as I did. Then I ran backend:dev and frontend:dev respectively.
2. Created a personal dev-compose.yml to get the bare minimum features up and running.
3. The API did not seem to use the .env file from either the root or api/.env, forcing me to modify the command to match the Port correctly for backend:dev.
4. The main branch isn't stable. Maybe I used the wrong branch, but ideally there should be a semi-stable branch that everyone operates from. I had to resolve a Cohere issue to run my instance. I think I've had similar issues in past attempts, which resulted in taking so long to get my first dev instance up and going.

Suggested Remedies

1. Here are a few feasible solutions:
   a. Transition to Turbo Repo. I have been utilizing monorepos for node/js/ts projects since workspaces were first added to yarn and Turbo Repo has proven to be a game changer in terms of how to work with them. It makes things easier all around.
   b. Switch to a more efficient workspace setup. The current arrangement seems like a chaotic blend of monorepo and other patterns, leading to disarray. A workspace revamp could be beneficial. Here is an example of a project that I have with a more standard yarn 1.x workspace. It's old, but the structure is still the same. The documentation isn't very good, but the repo structure should be familiar.
   c. Beef up the documentation if I'm missing something, but I still think there is some room for some of the above.
2. I'm not clear about the purpose of the main docker-compose.yml since deploy-compose.yml is what I use on 2 small scale production instances I have running, but it might be useful to establish this as the basic installation requirement for operating in dev mode. Alternatively, a dev-compose.yml, similar to the one I used, could work.
3. This might just be a bug with the initial steps that needs fixing.
4. Make the main a tested branch vetted by multiple people on an occasional basis. PRs can merge to another branch which gets periodically reviewed on a local machine and then rebase into the main.
   a. Alternatively, setup a CI/CD pipeline that blocks merges to main until the full suite of tests are ran. Everything including linting, type checking, and tests including playwright. This is a lot more work both up front and in the long term though... but it cuts out the tedium.

My dev-compose.yml file

services:
  mongodb:
    container_name: chat-mongodb
    ports:
      - "27017:27017"
    image: mongo
    restart: always
    volumes:
      - type: volume
        source: mongodb_data
        target: /data/db
    command: mongod --noauth
    security_opt:
      - label=disable
  meilisearch:
    container_name: chat-meilisearch
    image: getmeili/meilisearch:v1.7.3
    ports:
      - "7700:7700"
    env_file:
      - .env
    environment:
      - MEILI_HOST=http://meilisearch:7700
      - MEILI_NO_ANALYTICS=true
    volumes:
      - type: volume
        source: meilisearch_data
        target: /meili_data
    security_opt:
      - label=disable

volumes:
  mongodb_data:
  meilisearch_data:

Note: I intentionally did not include any of the other services that seem to be in development still.

[danny-avila]

Thanks for your feedback. The first thing I'll say is, ditch docker for developing on this project. It is dead simple without it. I'll do a quick write up for the list of commands I use.

[mawburn]

Well, on my work machine this isn't really feasible. I imagine that other people may run into similar limitations. I wouldn't want to install these things natively on my personal machine either, tbh. Just to avoid conflicts with other projects.

I know this isn't what you're referring to, but I forgot to mention that I do use podman on both machines.

[danny-avila]

Prerequisites:

• latest npm recommended
• node 18.x.x or 20.x.x
• git
• All required environment variables set in .env file
• VS Code is highly recommended (vim elitists are on their own)
• (Optional) Docker for using/testing meilisearch, rag_api, local mongodb etc. Docker Desktop highly recommended.
• (Optional) if not focused on container services, use MongoDB Atlas or a local installation of MongoDB to not rely on containers during development

All commands are from root of project, i.e.:

danny@computer:~/LibreChat$ 

Note: I won't go into complex branch management, other than pulling latest changes from main and how I apply latest changes, both on a local branch and the main branch. Any more than this is more general and applies as it would to any git project.

How I git

How I pull/update latest changes, branch off, etc.

For latest changes, keeping main branch clean

git checkout main
git fetch origin
git pull

Branching off, before changes

# from main branch after pull down
git checkout -b my-local-branch
# make changes

Updating my local changes, after main receives latest

# from main branch, after applying latest changes there
git checkout my-local-branch
git rebase main
# resolve conflicts, hopefully none, applies your local commits on top of HEAD of main

Workflow commands

Highly recommend to use terminal alias for shorthand versions of these commands.

Install everything, fresh (recommend after changes to package.json files)

npm run reinstall

Build data-provider (necessary after any changes under packages/data-provider)

npm run build:data-provider

‼️ Important: if using VS Code, you need to Restart JS/TS services for updated intellisense after running data-provider command

• in VS Code Command palette with a JS/TS file active, search and run "TypeScript: Restart TS Server"
  • Map this command to a keyboard shortcut for easy access (you may still need to have a JS/TS file active)

Build data-provider and build client-side code

npm run frontend

Run backend

npm run backend

Run vite frontend dev server (hot reloads)

# requires backend server running
npm run frontend:dev

Notes:

• for backend debugging, use VS Code Javascript Debug Terminal. Search online on how to install
• for frontend debugging, use browser dev tools on the vite frontend dev server
• search online on how to use debugger tools

Setting up Docker (optional)

This is only if you absolutely need docker services for development. I do not use them if I am focused on frontend-specific features, for example, as I can use either mongodb installed on my local machine or MongoDB Atlas.

The best thing to do is set up docker for normal usage as the guides instruct, but then use CLI or Docker desktop to turn off the librechat container. Use the override file as needed to expose ports.

You can also use your own container setup that doesn't need to be rooted in the project even. You can look at utils/docker/test-compose.yml for a compose file example that doesn't run the LibreChat service.

Debugging Docker builds (optional)

This is mainly for debugging frontend issues that are only present in Docker. Run docker as normal as long as it's accessible to your current machine (on localhost, port 3080)

Then run vite dev server, and you can debug the client-side code served by docker.

[danny-avila]

@mawburn I will move this to the docs so it's meant to be general. You can benefit off docker/container services as I wrote up, but mostly run the librechat API server and vite dev server locally for sanity sake.

[fuegovic]

We do have this guide in the official docs that would've answered some of your questions:
https://docs.librechat.ai/contributions/how_to_contribute.html
(feel free to make a PR to improve on it is something is missing from it)

Turbo Repo isn't possible because we support 2 package managers (npm & bun)

[fuegovic]

@danny-avila that doc I just linked already includes pretty much everything you explained here: #2379 (reply in thread)

Maybe we should have a better title for it to make it easier to find? 🤷‍♂️

[mawburn]

I did read through that, but it didn't really help too much honestly. The issues were more to do with the side services, like Mongo and what and the installation process. I do think that's where I found the npm ci but it doesn't explain what that does.

Turbo Repo isn't possible because we support 2 package managers (npm & bun)

Ah right, I forgot about bun being in there and wasn't sure what it was used for.

[mawburn]

Why do you support bun, if you don't mind me asking? What is it being used for?

[danny-avila]

Why do you support bun, if you don't mind me asking? What is it being used for?

experimental. it has some quirks still unfortunately, but would love to use it wholesale if I could. runtime/build time is greatly improved using it.