How to migrate to Turbo from Lerna for Monorepo managemnt.

icruzr93 — Fri, 06 May 2022 17:33:01 +0000

For this read is really recommended to have context about Lerna setup, otherwise you can find this a bit confusing due that I'm not explaining too much about its setup

As you might know, Lerna was deprecated, so we had to look up for an utility that could help us to replace the basis of Lerna, the chosen one was Turbo.

// Detect dark theme var iframe = document.getElementById('tweet-1519436453729734657-385'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1519436453729734657&theme=dark" }

TLDR

First of all we read this article which helped us to compare the different, and popular, tools that actually exists for Monorepo management:

https://monorepo.tools/

We moved to Turbo due these basic reasons:

We are migrating to Next.js and, if you don't know, Vercel is owner of both tools so on this way we felt that choosing Turbo could bring us a sense of alignment with the tools used.
Based on their documentation the migration seemed easy (and it was).

This was good enough for us to try it out first, don't hesitate on trying out other ones first.

Lerna Context

To start I need to let you know how we have structured our projects and how we used it for the MonoRepo management.

How we used to use Lerna:

We had it globally installed for both, local and ci.
We built packages at devtime on dev mode and once that is finished we start apps on dev mode.
We built "packages" on ci time and once that is finished we build apps.
We don't push nothing into private packages.

Project structure:

apps/
../app-a
../app-b

packages/
../package-a
../package-b

lerna.json
package.json

Commands used with Lerna:

# Bootstrap workspaces
lerna bootstrap

# Link lerna repos
lerna link

# Build the packages workspaces
lerna run build --scope="@company/package-a" --scope="@company/package-b"

# Build the project workspaces
lerna run build --scope="@company/project-a"

# Build the project workspaces
lerna run build --scope="@company/package-b"

Things to know

Turbo is being used for task running and caching.
Yarn workspaces is being used for symlinking packages.
Don't forget to delete node_modules and .lock files, otherwise you can find errors due the migration.

Migrating to turbo

On our case we are using it globally for both local and on ci, you can also install it directly on your package.json:

npm install --global turbo

Now you need to delete your lerna.json file and create your turbo.json file with the next content:

Link to Turborepo docs

For us it was enough to start migrating our commands, the fun thing about this is that you only need to run 1 command to build all app deps.

# Bootstrap workspaces
yarn install

# Build app a
turbo run build --scope="@company/app-a"

# Build app b
turbo run build --scope="@company/app-b"

(Not Recommended) In case you want something more explicit:

# Bootstrap workspaces
yarn install

# Build package a
turbo run build --scope="@company/package-a" --no-deps

# Build package b
turbo run build --scope="@company/package-b" --no-deps

# Build app a
turbo run build --scope="@company/app-a" --no-deps

You can modify turbo.json file to add more commands to take advance of it but on our case it was ok having it on this way and for other commands we are using yarn workspaces:

yarn workspaces run lint:fix
yarn workspaces run prettier:fix

Overview:

I hope this article can help you to start migrating to Turbo and hope it could help you migrate a more complex workflow than us.