Creating a scalable Monorepo for Vue - Workspaces
In the previous post, I mentioned so-called workspaces. This is a good starting point which also will show how to structure your future and existing projects. The first one (starting without any projects) is easy, the second (existing ones) requires a bit more work but with a bit of luck, everything should run smoothly. The below steps describe how to do this with yarn classic. You could use yarn berry (very similar) or pnpm as well. In pnpm this approach works slightly differently by adding such structure description to the pnpm-workspace.yaml file. The rest is quite similar. Wait, but why not npm? I've heard that it also has workspaces. AFAIK it's still not monorepo-ready due to serious problems with hoisting and the lack of ability to solve such dependencies. A good explanation of the struggle with npm caveats is provided in this article ;) Let's get to the work Create a new directory with a package.json file structured as follows: { "name": "your_company_or_so", "version": "1.0.0", "workspaces": { "packages": [ "apps/*", "libs/*", "whatever_else/*" ] }, "dependencies": { // all repeating dependencies } // ... } Add a bunch of sub-directories like apps, libs, etc. like in the sample package.json. Put your projects into the mentioned directories. Cut out the repeating dependencies and devDependencies from your projects package.json files in the sub-directories and place them in the package.json file in the root directory. These are now connected to all your projects - exceptions are possible (read below). Delete all your node_modules in the sub-directories Go to the root directory and install dependencies yarn install What about the dependencies that are not identical? First consider bringing them to the same version, preferably the newer ones. It's too time-consuming right now. I get it—deadlines, and so on. You can just leave them where they are. I would still strongly recommend having only one version of Vue, React, Typescript, etc., because the more packages tied to the same version, the easier it is to update all your projects at once and deal with refactors after updating all the projects in one go. Fine, I updated what I could, but there are still some dependencies requiring different versions. It's fine, there is nothing wrong with it. Decide which version is more common and move this one to the root package.json. The less common version will stay in the package.json file of the project that is using it. This way, you signal your package manager that you need that specific version in a particular project, and it will be installed independently. What about dependencies that are used only once? Should I move them as well? It's up to you. If you assume that they will be used more often, sure, move them. Are they used only once for this specific project, and it's highly unlikely that it will change? Nah, you don't have to move it and pollute the root package.json. Troubleshooting I have some problems with dependencies with different versions. You can try omitting this one migration to the root package.json file and keeping it in the projects package.json files instead. I have some problems with dependencies outside the node_modules in the project (moved to another directory). It's quite uncommon, but it happens. If you encounter such problems, consider nohoist option for yarn classic described here. Or even better, switch to yarn berry or pnpm. As far as I'm aware, they should be free of such problems.
In the previous post, I mentioned so-called workspaces. This is a good starting point which also will show how to structure your future and existing projects. The first one (starting without any projects) is easy, the second (existing ones) requires a bit more work but with a bit of luck, everything should run smoothly.
The below steps describe how to do this with yarn classic. You could use yarn berry (very similar) or pnpm as well. In pnpm this approach works slightly differently by adding such structure description to the pnpm-workspace.yaml file. The rest is quite similar.
Wait, but why not npm? I've heard that it also has workspaces.
AFAIK it's still not monorepo-ready due to serious problems with hoisting and the lack of ability to solve such dependencies. A good explanation of the struggle with npm caveats is provided in this article ;)
Let's get to the work
-
Create a new directory with a
package.jsonfile structured as follows:
{ "name": "your_company_or_so", "version": "1.0.0", "workspaces": { "packages": [ "apps/*", "libs/*", "whatever_else/*" ] }, "dependencies": { // all repeating dependencies } // ... } Add a bunch of sub-directories like
apps,libs, etc. like in the samplepackage.json.Put your projects into the mentioned directories.
Cut out the repeating
dependenciesanddevDependenciesfrom your projectspackage.jsonfiles in the sub-directories and place them in thepackage.jsonfile in the root directory. These are now connected to all your projects - exceptions are possible (read below).Delete all your
node_modulesin the sub-directories-
Go to the root directory and install dependencies
yarn install
What about the dependencies that are not identical?
First consider bringing them to the same version, preferably the newer ones.
It's too time-consuming right now.
I get it—deadlines, and so on. You can just leave them where they are. I would still strongly recommend having only one version of Vue, React, Typescript, etc., because the more packages tied to the same version, the easier it is to update all your projects at once and deal with refactors after updating all the projects in one go.
Fine, I updated what I could, but there are still some dependencies requiring different versions.
It's fine, there is nothing wrong with it. Decide which version is more common and move this one to the root package.json. The less common version will stay in the package.json file of the project that is using it. This way, you signal your package manager that you need that specific version in a particular project, and it will be installed independently.
What about dependencies that are used only once? Should I move them as well?
It's up to you. If you assume that they will be used more often, sure, move them. Are they used only once for this specific project, and it's highly unlikely that it will change? Nah, you don't have to move it and pollute the root package.json.
Troubleshooting
I have some problems with dependencies with different versions.
You can try omitting this one migration to the root package.json file and keeping it in the projects package.json files instead.
I have some problems with dependencies outside the
node_modulesin the project (moved to another directory).
It's quite uncommon, but it happens. If you encounter such problems, consider nohoist option for yarn classic described here. Or even better, switch to yarn berry or pnpm. As far as I'm aware, they should be free of such problems.
