• Home
  • Blog
  • Projects
  • Bookshelf
  • About
← Back to all posts

Monorepo Tips and Tricks

Published ....
Last modified ....

Share this post on BlueskySee discussion on Bluesky

I've been noodling on monorepos for a while now, and I wasn't sure how I wanted to start sharing some of my thoughts on managing monorepos and making it easier to work within them.

For context, I helped setup and manage a large scale web monorepo while I was at Wayfair, and I've done the same at Fireworks as well. While I don't claim to know everything about monorepos, I have a number of years working within them with a large number of contributors (and 100's of contributions to the main branch per week on average).

This post (and future posts about monorepos), focuses in on "node monorepos", e.g. those that use package managers like npm, bun, yarn, pnpm, deno, etc and where the code uses JavaScript/TypeScript, or otherwise usually relies on node_modules. However some of these recommendations may apply to other kinds of monorepos as well.

I plan to write a bit more about monorepos in the future, but I figured I should start with some top of mind tips and tricks (really just a set of recommendations). These are presented in no particular order - if you have any questions on these feel free to reach out!

Dependency Management

1. Always specify dependencies within the workspace that depend on them

Often when working within a monorepo - some dependencies may have been resolved by other workspaces within the repo. For example, if you have a React application and several libraries used within that application, the dependency is most likely installed by either the app or the libraries. This can make it really easy to accidentally forget to properly declare a dependency within a new workspace.

react

Your tests, or other flows may "just work", however you've created an implicit contract that could break depending on how your package manager resolves dependencies, or if you remove that dependency from other workspaces.

The same applies for in-monorepo dependencies, e.g. if you have a workspace that depends on another workspace within the repo - you should specify that as a dependency as well, usually following the format of "workspace-pkg": "workspace:*" which roughly means resolve the workspace-pkg dependency from the local workspaces at any version. See below for managing versions of workspace dependencies!

2. In-repo dependencies must always be one way

Circular dependencies should always be avoided - even if you're not working within a monorepo you want to avoid introducing circular dependencies because they could lead to undefined behavior at run time, or just generally introduce confusion for contributors.

If you have some code in pkg-a (which depends on pkg-b), that pkg-b would like to use - you should extract that code to a shared library that both can depend on (or copy it into both libraries).

3. Workspaces should build themselves

This one is a bit of a 🌶 spicy take 🌶, however I strongly believe that workspaces should have their own build steps, and other workspaces depending on those packages should consume the built artifacts.

This one is particularly important when working with TypeScript, TypeScript doesn't usually understand package boundaries and will continue type checking down through code within dependencies. Not only does this mean that TS will do more work than is necessary - it can sometimes also lead to weird race conditions or generate definition files within the source directory[1]Jump to footnote.

The only solid way I've found to avoid this pitfall is two changes:

  • Configure skipLibCheck within tsc, and
  • Build libraries to some kind of dist directory

On Versioning

There's a number of thoughts I have on versioning within monorepos.

1. Pin External Dependencies

First and foremost - you should always pin external dependencies to a specific version. The only case where you shouldn't pin a dependency, is when you're publishing a package to an external registry (e.g. npm or jsr), and that dependency is a peerDependency.

2. Always point to the latest version of local dependencies

I don't recommend using versioning for internal dependencies, for example if you have two packages in your repo pkg-a and pkg-b, and a depends on b, you don't need to specify a version for b within a's package.json. You can instead use workspace:* to depend on any version of the package, which should resolve the "current version" of that dependency within the repo. This would look like the following package.json:

{
  "name": "pkg-a",
  "dependencies": {
    "pkg-b": "workspace:*"
  }
}

It's worth noting however, that just because you always consume the latest version of a local dependency, doesn't mean that you can leverage versioning as a way to indicate historical significance to changes to the workspace.

I've seen teams adopt a healthy versioning and changelog process for monorepo packages in the past that helps to provide context on what changes have happened and why (with more nuance than git commit history).

3. Adopt a one version rule

This is something I become familiar with while at Wayfair, and have since tried to get others to adopt it as well. The concept comes from a paper by engineers at Google, and boils down to:

For every dependency in [a] repository, there must be only one version of that dependency to choose.

(originally from the book Software Engineering at Google)

I've published the one-version npm package to help enforce this constraint across monorepos with any package manager.

The gist here is to avoid weird edge cases where some dependencies may resolve to different versions - this has been known to cause issues with popular packages like React.

While this may make it difficult to tackle version upgrades on larger monorepos - the consistency afforded by using a single version for each dependency makes this worthwhile.

Footnotes:

↩Back to reference

While at Wayfair, we ran into one of these issues, we were seeing inconsistent failures during our CI pipelines, where the associated .d.ts files within a dependency would sometimes be present and sometimes they wouldn't. We tracked this down to a race condition when performing builds and also checking types in parallel across workspaces. Enforcing builds + skipLibCheck prevented this bug for us.

Tags:

Web DevelopmentMonorepos

Loading...

Related Posts

Web Development

Website Redesign v11

....

I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!

Onboarding Your New AI Teammate

....

Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?

Quick Tip - Theme Aware Images

....

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

Website Redesign v10

....

I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Podcasting By Hand

....

A brief overview on how we launched The Bikeshed Podcast, including a deep dive in our recording and distribution workflows!

Quick Tip - Specific Local Module Declarations

....

A quick tip outlining how to provide specific TypeScript type definitions for a local module!

On File-System Routing Conventions

....

Some rough thoughts on building a file-system routing based web application

You're Building Software Wrong

....

Slicing software: why vertical is better than horizontal.

Single File Web Apps

....

What if you could author an entire web application in a single file?

Resetting Controlled Components in Forms

....

A quick way to handle resetting internal state in components when a parent form is submitted!

A Quick Look at Import Maps

....

A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

Recommended Tech Talks

....

A collection of tech talks that I regularly re-watch and also recommend to everyone!

Request for a (minimal) RSC Framework

....

Some features and functionality that I'd like within a React Server Component compatible framework.

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

TSLite

....

A proposal for a minimal variant of TypeScript!

Next.js with Deno v2

....

This is a quick post noting that Next.js should now work with Deno v2!

Don't Break the Implicit Prop Contract

....

React components have a fundamental contract that is often unstated in their implementation, and you should know about it!

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

My Current Dev Setup

....

A quick look at the applications and tools that I (generally) use day to day for web development!

Abstract Your API

....

Proposing a solution for sharing core "business" logic across services!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Using Feature Toggles to De-risk Refactors

....

Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

Hohoro

....

A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Corporate Sponsored OSS

....

The various risks and pitfalls of open source software run by corporations.

The Library-Docs Monorepo Template

....

A monorepo template for managing a library and documentation together.

Building Better Beacon

....

How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.

Project Deep Dive: Tails

....

A(nother) deep dive into one of my recent side projects; tails - a plain and simple cocktail recipe app.

Churn Anxiety

....

When did semver major changes become so scary?

Service Monitors and Observability

....

Leveraging service monitors properly to improve service observability.

On Adopting CSS-in-JS

....

A brief recap of how Wayfair changed it's CSS approach not once but twice in the span of 5 years!

Project Deep Dive: Microfibre

....

A deep dive into one of my recent side projects; microfibre - a minimal text posting application

Pair Programming

....

Pair programming can be good sometimes - but not all the time

Suspense Plus GraphQL

....

A few thoughts on using Suspense with GraphQL to optimize application data loading

You've Launched, Now What?

....

A few thoughts on what to do after you launch a new project

Taking a Break

....

A few quick thoughts on burn out and taking a break

Managing Complex UI Component State

....

A few thoughts on managing complex UI component state within React

Understanding React 16.3 Updates

....

A quick overview of the new lifecycle methods introduced in React 16.3

CSS in JS

....

A few thoughts and patterns for using styled-jsx or other CSS-in-JS solutions

Redesign v6

....

A few thoughts on the redesign of my personal site, adopting Next.js and deploying via Now

JavaScript Weirdness

....

A few weird things about JavaScript

Calendar

....

Building a calendar web application