Tips and pitfalls of setting up a monorepo with Turbo, Nextjs, and Vercel

Monorepos in 2022

You may have already noticed but Monorepos are trending. They offer efficiency benefits can be hard to appreciate until you have experienced them. For example, was making a CI change at my company. I had to open 15 pull requests, one for each project. In every case I was adding a single line to a .yml file. Fifteen. Pull. Requests. In a monorepo this pipeline would have been a shared file. It would have been a single pull request with a single line.

Monorepos include many other benefits, but there are also some new challenges. Deployment and tooling become harder. Turborepo is a tool I have been using to manage my monorepo for Rune. I'm happy with the results. Now I can easily build, test, lint, pretty, or dev all of my projects simultaneously. I would like to share some of the tips and pitfalls. The described monorepo uses:

• Turborepo
• Yarn workspaces
• Vercel for deploys
• Next.js

Overview

This post is for people who manage multiple projects. You may be using separate repos right now, working on a monorepo, or debugging a problem. In my case, I have Next.js projects for blog, marketing, app, store, chat server, and shared components.

Basic setup

To set up Turbo just follow the guides below.

Yarn Workspaces

I prefer yarn to npm for many reasons, but you can also use npm workspaces.

Yarn workspaces can be set up by following this guide: https://classic.yarnpkg.com/lang/en/docs/workspaces/

Turborepo

Turborepo was straightforward to set up. I was just using a simple Makefile before switching to Turbo. I was pleased with the improvements, particularly I think the remote cache is fantastic.

Begin by following this guide: https://turborepo.org/docs/getting-started

Vercel Monorepo

I highly recommend deploying your monorepo with Vercel. They make it extremely convenient. Don't skip the Ignored builds step. Keep in mind it's relative to the defined project root. There is a limit of 3 projects on the free plan for monorepo.

Set up your projects according to this guide: https://vercel.com/docs/concepts/git/monorepos

Thoughts

Packages vs symlinks

Before Turbo I was using a shared folder that I symlinked into various projects. This allowed me to share components. I switched shared folder to a package and used paths property in tsconfig.json to allow easier importing. However the downside I encountered was that intellisense no longer was able to auto import or click into packages. This was a downside that disappointed me. I am going to continue investigating the pakage path to see how to mitigate these downsides. I noticed they are present in the ecommerce example from nextjs as well.

Gotchas

Cryptic Type Errors due to yarn workspaces

When we switched to workspaces we began seeing errors related to types that weren't even dependencies in our project. Example:

Type error: Cannot find type definition file for '__mocks__'.
  The file is in the program because:
    Entry point for implicit type library '__mocks__'

error Command failed with exit code 1.

This was easy enough to fix once you knew what to do. Add this to your tsconfig.json:

"compilerOptions {
  ...
  "typeRoots": ["node_modules/@types"]
}

Dangerous warnings due to yarn workspaces

When switching to yarn workspaces you need to keep an eye out for warnings, especially at the beginning. There is a chance for packages to collide with each other if you have not specified a specific version. This error cost me a day. Everything worked fine locally, but deploying on Vercel would fail with an error that I did not realize was due to this warning.

warning Pattern ["next@latest"] is trying to unpack in the same destination "/vercel/.cache/yarn/v6/npm-next-12.1.5-7a07687579ddce61ee519493e1c178d83abac063-integrity/node_modules/next" as pattern ["next@^12.0.8","next@^12.0.8","next@^12.0.8","next@^12.0.8"]. This could result in non-deterministic behavior, skipping.

The error I saw in Vercel console:

Error: `pages/404` can not have getInitialProps/getServerSideProps

The solution was to simply change a dependency in my other projects from:

next@latest to ^12.0.8

Errant warnings using JSX components

I received some errors relating to JSX components mounting. I suspect these were also caused by the warning above. However, these ones did have the ability to resolve by pinning a version.

'Component' cannot be used as a JSX component

Resolutions and overrides:

"resolutions": {
	"@types/react": "^17.0.1",
	"@types/react-dom": "^17.0.2"
},
"overrides": {
	"@types/react": "^17.0.1",
	"@types/react-dom": "^17.0.2"
}

Resources

If you want to peruse my sources they can be seen below:

• https://stackoverflow.com/questions/71809703/component-cannot-be-used-as-a-jsx-component?noredirect=1#comment127187138_71809703
• https://stackoverflow.com/questions/71985341/error-pages-404-can-not-have-getinitialprops-getserversideprops
• https://github.com/yarnpkg/yarn/issues/4812