My Dev Multirepo Setup for JS projects with dependencies

Joaquim Monserrat Companys — Wed, 17 Dec 2025 15:20:45 +0000

Suppose that you work for a company that has 2 JS apps: AppX, and AppY. These apps have common dependencies: DepZ, DepW. In this article we'll review how to work in parallel features at the same time involving all these dependencies using the following tools:

git worktrees
zoxide: https://github.com/ajeetdsouza/zoxide
ln (to create symbolic links)
zellij: https://zellij.dev/

Cloning the original repos

We create a root folder where all the projects will live:

mkdir ~/multirepo

Then inside this folder we clone all the 4 projects:

git clone https://github.com/user/appx ~/multirepo/appx0
git clone https://github.com/user/appy ~/multirepo/appy0
git clone https://github.com/user/depz ~/multirepo/depz0
git clone https://github.com/user/depw ~/multirepo/depw0

Later we'll see why I'm adding the suffix 0 to all the folders.

zoxide

After installing zoxide and setting the following alias in ~/.bash_aliases:

  alias cd='z'

Now I can jump to AppX with the following command

cd appx0

no matter which was the previous location.

If AppX in reality has name AwesomeAppX, we'll try to simplify the name to appx0 for navigating with fewer keystrokes to the desired directory. And is important that the string appx0 is unique in all my filesystem, if not zoxide can jump you to a wrong location.

git worktree

Now suppose that I have to work in AppX feature/A but we don't need to modify depZ neither depW. I'll create one worktree with the following command:

cd appx0
git worktree add ../appx1 -b feature/A

appx0 was at branch develop, and with the previous command we create a new directory with a new branch checked out into it. Now we can work with appx1 and develop the featureA.

We'll never work with worktree 0, this is the parent worktree (but you can if you want). These worktrees should be checked out at develop or master, and from these worktrees we'll create the other ones (1,2,3...).

In this way we can work with several features in parallel. And we have a unique git repo (stored at appx0) where all the commits and branches are stored.

worktrees + links

Now suppose that you have to work in a feature/B and that is required to modify depZ together with appX.

No problem at all, we'll create the following worktrees to work with:

cd appx0
git checkout develop
git worktree add ../appx2 -b feature/B

cd depz0
git checkout develop
git worktree add ../depzx2 -b feature/B

Here depz has the suffix x2 intentionally, because we want to remember that appx2 is linked with depzx2. But you can follow a different naming if you want.

For listing all our current worktrees together with the branches they are checked out we can run the following command:

cd multirepo

for d in */; do
  (cd "$d" && echo "$d" && git worktree list)
done

To link depz with appx, we'll use symbolic links:

cd appx2
npm install
rm -rf node_modules/depz
ln -s "../../depzx2" "node_modules/depz"

If we have configured our build tools to handle symbolic links, all will work as expected. Here you have some configurations that you have to tune if your build tools doesn't work well with symbolic links:

Anytime we can run these command to know if appx2 has some links active:

ls -la node_modules | grep depz

To see all the build tools of the dependencies plus the main apps working together, it is usefull to use Zellij (https://zellij.dev/).

Forem: Joaquim Monserrat Companys

My Dev Multirepo Setup for JS projects with dependencies

Cloning the original repos

zoxide

git worktree

worktrees + links

References