coil-monorepo-upkeep

Coil Monorepo Upkeep

Commands

• pnpm upkeep
• pnpm upkeep:new-package
• pnpm upkeep:check-updates

pnpm upkeep

This ensures the package configuration follows a convention by scripting the updates of various files like:

• jest.config.cjs
• tsconfig.build.json
• package.json
  • various scripts such as
    • pnpm build:ts
    • pnpm format
    • etc
• etc

History

What the upkeep command is, is an evolution of a small script we were working on a long time ago, when Adrian and I were experimenting with monorepo structure for the InterledgerJS set of packages.

The requirements were the following:

• Be able to work on any package without having to build its dependencies first

  • if you've used the Coil monorepo you'll know how painful it is to do this cold after a fresh clone.

• Running commit hooks on all the packages should scale

  • set up hooks just once in the root
    • helps GREATLY with performance
  • if linting is to work just once, then all the packages must share the same config

• Use the same version and configurations of eslint/prettier etc everywhere while allowing overrides

• Uniform naming for the set of local commands in each package (pnpm test, pnpm lint:all, etc)

• Able to use IDE refactoring tools across package boundaries

  • renames "just work"

  • This means that you need to open the whole repo in your editor and have it look it at is one set of sources.

    For this tsconfig.compilerOptions.paths is used.
    
    This is generated by upkeep, sourced from the package.json
    dependencies.
    

• However, we still want to be able to build only the dependencies, and use TypeScripts project references for cached builds.

  For this we create a tsconfig.build.json

    upkeep will generate the list of projects that a particular package
    depends upon, generating "path" : "..."} entries for the references
    section
  

• Depending on the task at hand, dynamic compilation (on the fly, with transpile only set to true) can be faster.

  Note that when upkeep was born, webpack's ts-loader' support for project references wasn't very flash. And at least the last time I checked project references and transpileOnly was mutually exclusive.

  This can matter more if you have a really slow computer (as I was using when I set up the repo)

To get all these things working at once it was much easier to script the shape and structure of the monorepo. In this way iterating on ideas was much faster and less error-prone (which can lead to confusions about how things work)

It was tricky to set things up where it always worked, so if something didn't work it was added to the CI (much easier/faster than testing everything by hand locally)

So when you see tests running under multiple configurations, it's testing that the monorepo is still structured in a way that it works in the various ways one may want to use it.