npm is the package manager for JavaScript. Find, share, and reuse packages of code from hundreds of thousands of developers — and assemble them in powerful new ways.

Kamil Khadeyev

A monorepo is a group of small projects that can be combined to build bigger projects, or they could just be small projects that doesn't know anything about the other projects.

One great thing about monorepos is that the code is available for everyone at every time. If you are a frontend engineer, and you're working in the blog application and you see that there is a bug in the backend application, you can go and fix it right away.

What are Monorepos

For this course, we are going to be using NPM Workspaces to configure our monorepo. We will have two workspaces, one for our apps and one for our libraries. We configure those in our package.json.

Configure NPM Workspaces in your Package.json

In order to create applications inside our monorepo, we can use different CLI tools like create-next-app or the Vite CLI. We'll install them inside the apps folder. We will create a blog and a dashboard app, one using create-next-app and the other using the Vite CLI.

It is also important to note that the only package-lock.json file that should exist, exists at the root of the project.

Install a Next.js and a Vite.js Applications Into a Monorepo

Creating a TypeScript library inside the monorepo is easy if we use tsup. To configure tsup, we have to set up the entry point. In our case, it's going to be the index.ts file inside the src directory.

We will also specify some extra options for tsup such as generating the types and source maps. We can also output different formats. In this case, we want to output an ESM file and a CommonJS file.

Add a TypeScript library to your Monorepo using TSUP

To run specific commands inside a monorepo we have to type `npm run` then the name of the command, `build`. We then add the flag `-w` for watch mode and specify which package we want to run the build command. In this case, it’s going to be the `utils` package. 

The full command will look like, `npm run build -2 @monorepo/utils`.

If you want to run all of the commands, you'll need to add the `-ws` flag. 

The full command for running all of our build commands will look like, `npm run build -ws`. 

Run App Specific Commands in a Monorepo

We can install a dependency inside a monorepo by running npm install, then the name of the dependency, in our case, it’s going to be Lodash. But, we are going to add different flags to that.

If we use the `-w` flag, we would have to specify in what package we want to install Lodash. We will do this for `monorepo/utils`. We could also use the `-ws` flag to install Lodash across all the packages in the monorepo. We can also use `-W` in uppercase to install Lodash in the root of the project.

Install Dependencies for Specific Packages in a Monorepo

Right now, it is not possible to run all the Dev Scripts across all the packages of the monorepo at the same time, because once we run `npm run dev` with the `-ws` flag, we will run the dev-command in the block first, but that command never ends. It is always watching for changes.

In order to run the `dev` scripts across all the packages in the monorepo, the first thing that we have to do, is to create a dev command for each one of the packages in the root package.json file. Then we can use `concurrently` to change them. We go `concurrently` and we tell it to run the utils, then the blog and then the dashboard scripts.

Run Dev Scripts for All Packages Simultaniously

We already have a utils package that outputs JavaScript. If we want to use that package inside any of our applications, in our case, blog or dashboard, we would have to install it first.

Share Code Between a Library and Applications Inside a Monorepo

All of our applications and libraries have `test` and `typecheck` commands already written inside of them. We are able to run both the `test` and `typecheck` commands all at the same time as well. 

This has a downside. They don’t run at the same time, it’s just one after the other. To make them run at the same time, we will implement `concurrently` again.

Running Quality Checks in your Monorepo

Thank you for completing my course!

You’ve learned what monorepos are, how to create them from scratch, how to install different projects inside of it, and how to run different scripts inside of a monorepo. 

So where do you go from here? I suggest creating your own Monorepo project template and publish it on Github. Take a look at Yarn Workspaces, pnpm, Learna, Nx and Turborepo for different monorepo tools. 

I also highly suggest Migrating some of your existing projects to a monorepo. Have a main frontend application that consumes a shared UI library package and a backend service. Another way would be to have a backend service, a mobile application and a frontend application. 

Best of luck and happy coding!

Intro to Monorepos with NPM Workspaces Outro

In this course, Juri Strumpflohner demonstrates how to create a Digital Garden through the iterative creation of a React + Storybook.

Architect an Extensible Digital Garden with Next.js, Tailwind, and Nx

Learn Remix by building a full-featured blog with a database, authentication, CRUD operations, user roles, and more!

Up and Running with Remix

Learn Remix by building a social media platform powered with TypeScript and Prisma.

Learn Remix by Building a Social Media Platform with TypeScript and Prisma

Introduction to Monorepos with NPM Workspaces

https://app.egghead.io/api/v1/lessons/npm-what-are-monorepos/subtitles

Instructor: [0:00] Let's talk about monorepos. A monorepo is a group of small projects that can be combined to build bigger projects, or they could just be small projects that doesn't know anything about the other projects.

[0:15] For instance, you can take Next.js as an example. The Next.js project is a monorepo that contains many projects inside of it. For instance, in a monorepo, you could have a blog application, a backend application, and a dashboard application, and those application, they don't know anything about each other. They are completely independent.

[0:36] In a monorepo, you could have shared packages. For instance, we have this lib1, lib2, and lib3. They share code between some of the applications. If we were not using a monorepo, we could have this lib1 as an npm package, and we would have to publish it alone and then make blog application and dashboard application consume them.

[1:02] One great thing about monorepos is that the code is available for everyone at every time. If you are a frontend engineer, and you're working in the blog application and you see that there is a bug in the backend application, you can go and fix it right away.

[1:17] You don't have to clone a different repo. You don't have to open a peer in a different repository. All that you have to do is to open the backend application, fix the bug, and then push a fix, and it will fix the bug for every other application that uses it.

[1:33] For instance, if you have TypeScript types in the backend application, and you want to share them with the frontend, you can do it. You can just put those types in this lib2, for example, and then share them with the blog application.

[1:47] It's important to know that a monolith is different from a monorepo. A monolith is a group of projects that can form one big project. In this case, it's this application, and this application depends on all these shared packages.

[2:05] For instance, if you break something in this shared package, you don't know if this shared package is going to break, or this is going to break, or this is going to break, because there are no clear boundaries between them. If you remember, in the monorepo, we have the libs completely isolated from each other, but here, everything depends on everything.

https://app.egghead.io/api/v1/lessons/npm-what-are-monorepos/transcript

https://app.egghead.io/api/v1/lessons/npm-configure-npm-workspaces-in-your-package-json/subtitles

Alejandro Ñáñez: [0:00] Let's start by creating our package.json file by running npm init -y.
[0:05] Now let's have the workspaces key, which is the one that will tell NPM to behave like a monorepo. Here, in this workspaces array, we are going to add all the folders that we want to be added to our monorepo. For this course, we are going to use apps and everything that is inside of it, and we are also going to use libs. Let's clean up things a little bit because we do not need test for now.

[0:32] Now, let's update the name property to monorepo. This could be anything, but the convention that we would like to use is the @ symbol and then the name of your company or your own name and all this is because in the future, when we have many packages in our monorepo, we will start calling them @monorepo/mypackage1, 2 and so forth.

[0:59] To recap, in order to have a monorepo managed by NPM Workspaces, we will need to add the workspaces property with an array of strings. Each one of the strings in the array represent the folder that will contain applications, libraries and whatever we want. This could also be just one folder, but for organization purposes, I prefer to use apps and libs.

[1:22] It is not mandatory, but it's a good practice to update the name of your package.json file with something that it starts with @, and then followed by your company name or your own name. We will have a standard way to name your packages in applications inside the monorepo.

https://app.egghead.io/api/v1/lessons/npm-configure-npm-workspaces-in-your-package-json/transcript

https://app.egghead.io/api/v1/lessons/npm-install-a-next-js-and-a-vite-js-applications-into-a-monorepo/subtitles

Instructor: [0:00] Let's begin by creating an apps folder. All right. Now, we're going to create a Next.js application and for that, we're going to use create-next-app. This new application is going to be called blog and it will live inside apps. Then we have to specify that we want this to be a TypeScript application, that we also want to use npm.

[0:27] Now, we are creating a React application using Vite.js. Let's cd into apps. We're going to run npm create vite@latest. We are going to call this project dashboard. We want this project to be a React project. We also want this project to use TypeScript.

[0:51] We can go back to the root of the project. Let's open the blog/package.json file and let's update its name property. This is going to be called monorepo/blog. Let's do the same for the dashboard. Let's update its name to add monorepo/dashboard. Let's run npm install from the root of the project.

[1:19] All right. One thing that is worth noting is that blog doesn't have any package-lock.json file, and neither dashboard. We just have a package.json file inside here, and inside here. The only package-lock.json file that exists, it exists in the root of the project.

[1:42] If we take a look inside its package object, we'll see that we have a monorepo package, and we also have two more packages here. One is apps/blog and its name is monorepo/blog. We also have an apps/dashboard with its name set as monorepo/dashboard.

[2:04] To recap, in order to create applications inside our monorepo, we can use different CLI tools like create-next-app or the Vite CLI. We need to install them inside the apps folder. Here we have the blog. We also have the dashboard. It is also important to note that the only package-lock.json file that should exist, exists in the root of the project.

https://app.egghead.io/api/v1/lessons/npm-install-a-next-js-and-a-vite-js-applications-into-a-monorepo/transcript

https://app.egghead.io/api/v1/lessons/npm-add-a-typescript-library-to-your-monorepo-using-tsup/subtitles

Instructor: [0:00] Let's begin by creating addlibs folder. Now, let's see the into libs. Let's create an utils folder. Let's see the into the utils folder. Let's create an empty package.json file. Let's edit that file. The first thing that we want to do is to update its name to be @monorepo/utils.

[0:26] Since we are using tsup to bundle our TypeScript code, we would need to install that tsup package first. Let's begin by running npm install tsup. Then we're going to save it as a dev dependency, and we want to save it inside the monorepo/utils package.

[0:46] Let's start by creating a tsup object inside the package.json file. We are going to set the entry point to be src/index.ts. Then we are going to configure tsup to generate the TypeScript definitions.

[1:06] We also want to generate source maps. We set this source map key to true. Then we specify the formats that we want tsup to output. This is an array that will contain ESM because we are interested in getting an ESM version of our package. We are also interested in getting a CommonJS version of our package.

[1:30] Since tsup will generate JavaScript files inside the dist folder, we will have to update the main property to dist/index.js. We will also have to add the module property to be dist/index.mjs. The last thing that we have to do here is to update the scripts object.

[1:57] We have to create two scripts. One is the dev script that is going to run tsup in watch mode. The other one is the build script which is going to run tsup.

[2:10] With that configuration in place, we want to create a new file. This file is going to be called index.ts and it will live inside the src folder. We are going to export a constant that is called copyright. Its value is going to be egghead.io.

[2:30] To recap, creating a TypeScript library inside the monorepo is easy if we use tsup. To configure tsup, we have to set up the entry point. In this case, is going to be the index.ts file inside the src directory.

[2:48] We can also specify some extra options for tsup. We can generate the types. We can generate source maps, and we can also output different formats. In this case, we want to output an ESM file and a CommonJS file.

[3:06] It is worth noting that tsup will generate those files inside the dist folder, so we have to update main and module accordingly. The last thing is that we have to create some npm scripts to make tsup work. We created a dev script that calls the tsup CLI in watch mode. We also create a build script that runs tsup.

https://app.egghead.io/api/v1/lessons/npm-add-a-typescript-library-to-your-monorepo-using-tsup/transcript

https://app.egghead.io/api/v1/lessons/npm-run-app-specific-commands-in-a-monorepo/subtitles

Alejandro Ñáñez: [0:00] To run in a specific command inside a package of a monorepo, we have to type npm run, then the name of the command, and then we have to add the -w flag. Here, we have to specify in which package we want to run the build command. In this case, it's going to be in utils.

[0:20] Here, you can see that we are running the build script inside a utils package of the monorepo. If what we want is to run the build command across all the packages in the monorepo, we will have to add the -ws flag.

[0:36] Now that the command has ended, we can see that we are running build in the block project first, then we are running build in the dashboard project, and then we are running build inside the utils project.

[0:49] To recap. Running commands inside an npm workspaces monorepo is easy. We just have to type npm run, then the name of the command, and then we can add the -w flag to specify where we want to run that command, or we can add the -ws flag to run that command across all the packages in the monorepo.

https://app.egghead.io/api/v1/lessons/npm-run-app-specific-commands-in-a-monorepo/transcript

https://app.egghead.io/api/v1/lessons/npm-install-dependencies-for-specific-packages-in-a-monorepo/subtitles

Instructor: [0:00] We would install an npm package inside a package of a monorepo by running npm install, then the name of the package. Then we add the -w flag. We specify where we want it. In this case, we want to install Lodash inside the utils package. Let's check out the package.json file inside the utils folder. There you have it. We have Lodash.

[0:23] If we run git status, we'll see that we have modified the package.json file inside the utils package. We could install Lodash across all the packages in the monorepo by adding the -ws flag.

[0:38] Now, let's run git status to see what has changed. Yes, the app's package-lock.json file has changed. Same for the dashboard and same for the utils.

[0:48] We could also install one dependency in the root of the monorepo by running npm install, the name of the dependency, then we use the -W, this time with uppercase. Let's run git status to see what has changed. This time, we modified the package.json file that is in the root of the project.

[1:08] To recap, we can install a dependency inside a monorepo by running npm install, then the name of the dependency, in this case is going to be Lodash. We are going to add different flags.

[1:20] If we use the -w flag, we would have to specify in what package we want to install Lodash. In this case, it could be monorepo/utils. We could also use the -ws flag to install Lodash across all the packages in the monorepo. We can also use -W in uppercase to install Lodash in the root of the project.

https://app.egghead.io/api/v1/lessons/npm-install-dependencies-for-specific-packages-in-a-monorepo/transcript

https://app.egghead.io/api/v1/lessons/npm-run-dev-scripts-for-all-packages-simultaniously/subtitles

[0:00] Instructor: Right now, it is not possible to run all the Dev Scripts across all the packages of the monorepo at the same time, because once we run npm run dev with the WS flag, we will run the dev-command in the block first, but that command never ends. It is always watching for changes. 

[0:21] Then if I stop that command by hitting Ctrl C, we will see that we are running the vid-server as well. Then if I stop it again, we'll see that we exit. To fix this, we are going to install a package called concurrently. Let's run npm install concurrently.

[0:41] Concurrently is going to be installed in the root package.json of the monorepo. It's also going to be the dependency. Let's add a couple of scripts. We're going to create one script to run the Utils project. What this script is going to do, is that it's going to run npm run dev.

[1:01] For the workspace, monorepo/utils. We are going to duplicate that two times because we have two projects. Let's replace utils with blog. Let's replace it with dashboard. Now that we have all these three commands, we are going to create the dev script.

[1:26] This script is going to run concurrently. We have to skip double quotes here. Let's do that. We are going to take concurrently to run the npm script that is called dev details. We're going to do the same for the other two commands that we have left.

[1:49] This one is now details. This one is blog, and this one is going to be dashboard. We can run the dev script that we just created, and you'll see that we are running the dev command in the utils package. We are also running the dev command in the blog package, and we are running the dev command in the dashboard package.

[2:15] To recap, in order to run the dev scripts across all the packages in the monorepo, the first thing that we have to do, is to create a dev command for each one of the packages in the root package.json file. Then we can use concurrently to change them. We go concurrently and we tell it to run the utils, then the blog and then the dashboard scripts.

https://app.egghead.io/api/v1/lessons/npm-run-dev-scripts-for-all-packages-simultaniously/transcript

https://app.egghead.io/api/v1/lessons/npm-share-code-between-a-library-and-applications-inside-a-monorepo/subtitles

Man: [0:00] Let's install the monorepo-utils/package as a dependency inside the monorepo dashboard project, and inside the monorepo/blog project.

[0:14] If we take a look at the package.json file inside the blog, we'll see that we are using the monorepo-utils version 1. The same is true for the dashboard project. We are using monorepo-utils in version 1.

[0:30] Now that we have installed the monorepo-utils package inside the dashboard, we can use it in our application. Let's import copyright from monorepo-utils, and we are going to use it here next to Vite and React.

[0:51] Let's do this copyright. We save the page and we see that this has changed. We will do the same for the blog. Let's open the blog pages and then let's open this index.tsx. Let's do the same thing.

[1:10] Welcome to Next.js, let's change this to copyright. This code will allow to import these for us. Let's take a look at the application. Let's reload the page, and we'll see that it says, egghead.io.

[1:31] Let's go to libs and change index.tsx. Let's uppercase the first letter. As you can see, we can see the change here. It is also reflected here.

[1:45] Also, please note that we are importing copyright from @monorepo-utils. We are not using relative paths here, like these styles.

[1:56] We are using the name of the package that we have inside the utils package, package.json file, and this is the name that we are using in dashboard, blog to import the utils package.

[2:12] To recap, we already have a utils package that outputs JavaScript. If we want to use that package inside any of our applications, in this case, blog or dashboard, we would have to install it first.

https://app.egghead.io/api/v1/lessons/npm-share-code-between-a-library-and-applications-inside-a-monorepo/transcript

https://app.egghead.io/api/v1/lessons/npm-running-quality-checks-in-your-monorepo/subtitles

Alejandro Ñáñez: [0:00] We already have Jest and the TypeScript compiler set up to look for any possible errors in our project.

[0:07] Let's take a look at the package.json. In the utils project, we have a test command that runs Jest, and we also have a typecheck command that runs a TypeScript compiler against certain files.

[0:20] The same is true for our project, so let's take a look at the dashboard. We have this test command that runs the tests for the dashboard project, and the same for the typecheck command. If we open the blog, which is a Next.js application, we'll see that we have Jest, and we have our typecheck as well.

[0:43] It also means that we can run all the tests in one command by running npm run test, and then we have the ws flag. Here, you can see that we're running the test in the utils project, the tests in the dashboard project, and the tests in the blog project.

[1:00] The same is true for the typecheck command. Surely, we are running the typecheck command in every project, but this has a downside, we are running all these tasks sequentially, so we run the blog typecheck command. Once that is done, we run the typecheck command in the dashboard and then we run the typecheck command in the utils project.

[1:26] We can improve this by using concurrently. Here we are in the package.json file in the root of the project and we are going to duplicate these commands, so let's make a few of them. This dev utils is going to be called...Let's change this to run the tests. Now, let's change this script to run the typecheck command. Let's add a missing comma here.

[1:53] We're going to create the check script, so this is going to use concurrently, right? Here we are going to escape some quotes. Let's do that here. We are going to run npm call on the test, right? Then we are going to use the * and what this is going to do is that it is going to run all the npm scripts that start with test: .

[2:20] Let's duplicate that and we are going to do the same for typecheck. We are going to add a flag that is called killOthersOnFail. This means that we're going to exit the check process if any of the tests or any of the typecheck fails.

[2:43] We're going to run npm run check. It finished, so let's take a look. It is running test for blog, it is running test for dashboard, it is running typecheck for utils, and so on and so forth. In the end, everything passed, so we don't get any error. We're going to change this 4 for a 5 so the test fails, and we're going to run npm run check again.

[3:12] Let's scroll up a little bit, and we see that this test fails in the test utils. It says that basically, we exit earlier because the test in the utils package failed. This is really useful in a CI environment because you don't want to run all your checks if one of them fails. You want to exit early.

[3:35] To recap, we have one npm script to run the test in each one of the projects, and we have one npm script to run the typecheck command in each one of the projects. With all that in place we have created the check npm script, and this script is going to run all the tests and all the typecheck scripts that we have below in parallel.

[3:58] We also added the kill or some fail flag so we exit earlier, if any of the tests fail or any of the typecheck checks fail.

https://app.egghead.io/api/v1/lessons/npm-running-quality-checks-in-your-monorepo/transcript

https://app.egghead.io/api/v1/lessons/npm-intro-to-monorepos-with-npm-workspaces-outro/subtitles

Instructor: [0:00] Hey, thanks for completing the course. We have learned what monorepos are, how to create a monorepo from scratch using npm workspaces. We also learn how to install different projects inside a monorepo.

[0:14] In this case, we used Next.js, we used Bit, and we used tsup, but you can use whatever you want. You can use Vue, you can use [inaudible], you can even create a mobile project using React Native. We also learned how to run different scripts in a monorepo. We took a look at how to create a script that takes care of the quality of a project, that runs the tests and the type checks for the project.

[0:41] Where you can go from here? A good way to learn about monorepos is create your own. I would suggest you to create a GitHub project and start doing things.

[0:53] For instance, you can take a look at the Next.js project if you need any inspiration. Once you have the project ready, you can create a GitHub template so you can use it in every project you want. I would recommend you to take a look at Yarn workspaces, pnpm, Lerna, Nx, and Turborepo, as those are all the ways to create monorepos in JavaScript.

[1:18] If you want to solidify your knowledge about monorepos, I would suggest you to migrate existing projects into a monorepo. One good example is to grab a front-end application that consumes a shared UI library package, move those projects into the monorepo, and go from there.

[1:36] Another good project to tackle is to move a back-end service, maybe a mobile application, and a front-end application into one single repository. I hope you have fun.

https://app.egghead.io/api/v1/lessons/npm-intro-to-monorepos-with-npm-workspaces-outro/transcript

Introduction to Monorepos with NPM Workspaces

Alejandro Ñáñez

You might also like these resources:

Architect an Extensible Digital Garden with Next.js, Tailwind, and Nx

Up and Running with Remix

Learn Remix by Building a Social Media Platform with TypeScript and Prisma

Credits

Course Content

You might also like these resources:

Architect an Extensible Digital Garden with Next.js, Tailwind, and Nx

Up and Running with Remix

Learn Remix by Building a Social Media Platform with TypeScript and Prisma