Migrating to a Monorepo

Migrating from a multi-repo setup to a monorepo setup can bring enormous benefits for productivity, especially if:

  • You're finding it hard to share code between applications
  • You want a unified approach on how your team builds code

It can be daunting to move to a monorepo. But with careful planning, it can go pretty smoothly.

Folder structure

Let's imagine your multi-repo setup looks like this:

web (repo 1)
├─ package.json

docs (repo 2)
├─ package.json

app (repo 3)
├─ package.json

You've got three repositories, web, docs and app. They don't have any shared dependencies, but you've noticed lots of duplicated code between them.

The best way to organise them in a monorepo would be like so:

my-monorepo
├─ apps
│  ├─ app
│  │  └─ package.json
│  ├─ docs
│  │  └─ package.json
│  └─ web
│     └─ package.json
└─ package.json

To start sharing code, you could use the internal package pattern, resulting in a new packages folder:

my-monorepo
├─ apps
│  ├─ app
│  │  └─ package.json
│  ├─ docs
│  │  └─ package.json
│  └─ web
│     └─ package.json
├─ packages
│  └─ shared
│     └─ package.json
└─ package.json

If you're planning to move to a monorepo, try sketching out the exact folder structure you're aiming for.

Setting up workspaces

Once your apps are in the right folder structure, you'll need to set up workspaces and install your dependencies. Our sections on setting up workspaces should help.

Handling tasks

Now your workspaces are set up, you'll need to figure out how you're going to run your tasks in your new monorepo. We've got sections on:

  1. How to configure tasks with Turborepo.
  2. How to set up your development tasks
  3. How to set up linting
  4. How to build your application
  5. How to set up testing