Turborepo Mono Repo Template

Introduction

This repository showcases using a monorepo to house a design system and the various packages one could contain. It is built for React and uses a number of different tools to create and maintain packages:

• 🏎 Turborepo — High-performance build system for monorepos
• 🔐 Commitlint — Checks commits follow conventional commits format
• 📋 Changesets — Managing versioning, publishing and changelogs
• 🛠 GitHub Actions — Running workflows in continuous integration

What is a Turborepo ?

Turborepo is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching.

Using Turborepo simplifes managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. Learn more about how monorepos improve your development workflow.

Turborepo is configured in CI/CD to only test packages that have changes detected in their workspaces, and, workspaces that depend on said package. For example, if Package A depends on Package B, and Package B changes, then turborepo will ensure both packages have their tests run.

Main Features & Benefits

Highlights of benefits from using this monorepo are:

• Turborepo caching so commands don't re-run unless changed detected.
• Internal packages to house common configuration for tools like ESLint, TypeScript.
• Type-checking method within each package that turborepo can cache.
• Shared Storybook (apps/docs) across all React related packages.

Utilities

This Turborepo has some additional tools already setup for you:

• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting

Versioning & Publishing Packages

• pnpm add-changeset - Generate a changeset file
• pnpm version-packages - Update versions, changelogs and dependencies of packages.
• pnpm release - Publishes changes to package registry and creates git tags.

The monorepo uses Changesets to manage versions, create changelogs, and publish to the package registry. You'll need to create an NPM_TOKEN and GITHUB_TOKEN and add it to your GitHub repository settings to enable access to the package registry.

Generating the Changelog

To generate your changelog, run pnpm add-changeset locally:

1. Which packages would you like to include? – This shows which packages and changed and which have remained the same. By default, no packages are included. Press space to select the packages you want to include in the changeset.
2. Which packages should have a major bump? – Press space to select the packages you want to bump versions for.
3. If doing the first major version, confirm you want to release.
4. Write a summary for the changes.
5. Confirm the changeset looks as expected.
6. A new Markdown file will be created in the changeset folder with the summary and a list of the packages included.

These changeset files should be part of your PR and committed into the trunk branch, ready for future release.

Releasing

When you merge your PR into the trunk branch, the GitHub Action will create a PR with all of the package versions updated and changelogs updated. If more PRs get merged with more changesets then the PR opened by the GitHub Action will be updated.

Merging this PR will, along with updating all of the files it changed, make the GitHub Action trigger it's release cycle where it attempts to publish each package within the workspaces package file.

Build

To build all apps and packages, run the following command:

cd my-turborepo
pnpm build

Develop

To develop all apps and packages, run the following command:

cd my-turborepo
pnpm dev

Remote Caching

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.

By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can create one, then enter the following commands:

cd my-turborepo
npx turbo login

This will authenticate the Turborepo CLI with your Vercel account.

Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo:

npx turbo link

Useful Links

Learn more about the power of Turborepo:

• Tasks
• Caching
• Remote Caching
• Filtering
• Configuration Options
• CLI Usage