adding-new-packages.md

Adding new packages to the monorepo

Note

If you're migrating an existing package to the monorepo, please see the package migration documentation. You may be able to make use of create-package when migrating your package, but there's a lot more to it.

Manually creating a new monorepo package can be a tedious, even frustrating process. To alleviate that problem, we have created a CLI that automates most of the job for us, creatively titled create-package. To create a new monorepo package, follow these steps:

1. Create a new package using yarn create-package.
   • Use the --help flag for usage information.
   • Once this is done, you can find a package with your chosen name in /packages.
2. Make sure your license is correct.
   • By default, create-package gives your package an MIT license.
   • If your desired license is not MIT, then you must update your LICENSE file and the license field of package.json.
3. Update .github/CODEOWNERS and teams.json to assign a team as the owner of the new package.
4. Add your dependencies.
   • Do this as normal using yarn.
   • Remember, if you are adding other monorepo packages as dependents, don't forget to add them to the references array in your package's tsconfig.json and tsconfig.build.json.

And that's it!

Contributing to create-package

Along with this documentation, create-package is intended to be the source of truth for the process of adding new packages to the monorepo. Consequently, to change that process, you will want to change create-package.

The create-package directory contains a template package. The CLI is not aware of the contents of the template, only that its files have placeholder values. When a new package is created, the template files are read from disk, the placeholder values are replaced with real ones, and the updated files are added to a new directory in /packages. To modify the template package:

• If you need to add or modify any files or folders, just go ahead and make your changes in /scripts/create-package/package-template. The CLI will read whatever's in that directory and write it to disk.
• If you need to add or modify any placeholders, make sure that your desired values are added to both the relevant file(s) and /scripts/create-package/constants.ts. Then, update the implementation of the CLI accordingly.
• As with placeholders, updating the monorepo files that the CLI interacts with begins by updating /scripts/create-package/constants.ts.