How to migrate your single-repo to a monorepo

I recently realized the need to migrate the projects I was working on to a monorepo and documented the process, so in this post I will teach you what a monorepo is and how to migrate your single repo next projects to a monorepo using turborepo as and share its components between them.

1. What is a Monorepo?

in a simple way monorepo is a single repository containing multiple distinct projects, with well defined relationships, understand more about monorepos here.

2. What problem does it solve?

My problem was that there were many projects that need the same components and configurations between them, so I joined Turborepo to facilitate maintenance.

3. How to migrate?

Come on, to start the migration you need to install turbo globally in your project

npm install turbo --global

Next we need to add a file called turbo.json containing the following information to the root of your project.

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "deploy": {
      "dependsOn": ["build", "test", "lint"]
  },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

If after this you can run turbo build everything went perfect.

Now let's configure the workspaces.

Turbo is built on top of Workspaces, a way of managing multiple packages from within a single monorepo package.

the name you give in package.json is the name of your workspace.

he default structure is add this to root's package.json.

{
  "workspaces": ["packages/*", "apps/*"]
}

And create 2 folders in the project root, one called packages and the other apps.

In the apps folder will be where your next projects are located and in the packages your libraries that will be shared.

Then move your complete next project to the apps folder.

And adds a new package.json that will be related to this. project

The structure should look something like this.

At this point you can add several projects to the apps folder.

Now let's create the first shared package.

For this we will add a folder called ui inside the packages folder.

And we will add 3 files, the first of which is the package.json referring to our ui package.

Containing the following information

{
  "name": "my-lib", 
  "main": "./index.ts",
  "dependencies": {
    "react": "^18",
  },
}

Name will be the name of your package and main refers to the entrypoint of your package.

The second file we will create will be our component

we will add called Button.tsx

import React from "react";


export default function Button() {
  return <div>Chad Button</div>
}

And the last one is index.ts in which our package.json references, containing the export of our button.

export * from './Button'

Now we need to install the package in the projects we want, so let's add my-lib by passing * the dependencies of the projects we want to use

"name": "admin",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "my-lib": "*",
    "next": "^14.0.2",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },

If you are using next 13 + you will need to add this to next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['my-lib'],
};

module.exports = nextConfig;

After that, just run npm install and run turbo dev!

Click here for the repository to ask questions, and if you have any problems, you can contact me on LinkedIn by clicking here.

I will see you in the next one,

Victor