Monorepos? What the heck!

Documentation

Turborepo is a blazing fast build system for JavaScript/TypeScript monorepos: codebases containing multiple projects, often using multiple frameworks, in a single unified code repository. Monorepos have many advantages, but they require appropriate tooling in order to scale. Turborepo provides this tooling and more.

https://turborepo.org/docs

What is a Monorepo?

• "The Google codebase includes approximately one billion files and has a history of approximately 35 million commits spanning Google's entire 18-year existence." [2016]

• "Google's codebase is shared by more than 25,000 Google software developers from dozens of offices in countries around the world. On a typical workday, they commit 16,000 changes to the codebase, and another 24,000 changes are committed by automated systems." [2016]

Why use a monorepo?

Structure of a monorepo?

- apps/
--- app-one
--- app-two
- packages/
--- package-one
--- package-two
--- package-three

- apps/
--- app-one
--- app-two
- packages/
--- ui
--- utilities
--- eslint-config
--- ts-config

{
  "dependencies": {
    "ui": "*",
    "utilities": "*",
    "eslint-config": "*"
  },
}

How to create a monorepo?

git clone git@github.com:bigstair-monorepo/monorepo.git

cd monorepo
yarn install

- apps/
--- docs
- packages/
--- bigstair-core
--- bigstair-map
--- eslint-config-bigstair
--- ts-config-bigstair

- apps/
--- docs
- packages/
--- core
--- map

yarn dev

import * as React from 'react';

export interface ButtonProps {
  children: React.ReactNode;
}

export function Button(props: ButtonProps) {
  return <button>{props.children}</button>;
}

Button.displayName = 'Button';

"dependencies": {
  "@bigstair/core": "*",
  "@bigstair/map": "*",
  "react": "18.0.0",
  "react-dom": "18.0.0"
},

import { Button } from '@bigstair/core';

Workspaces in Monorepos

"workspaces": [
  "packages/*",
  "apps/*"
],

cd apps
git clone git@github.com:bigstair-monorepo/app-vite-js.git
git clone git@github.com:bigstair-monorepo/app-vite-ts.git
cd ..
yarn install

• First, the new applications in apps need to install all their dependencies -- including the packages which they define as dependencies as well.

• Second, with two new nested workspaces coming in, there may be new dependencies between apps and packages that need to be resolved in order to have all workspace working together.

"dependencies": {
  "@bigstair/core": "*",
  "@bigstair/map": "*",
  ...
}

import { Button } from '@bigstair/core';

Monorepo Tools

yarn dev

yarn lint
yarn build
yarn clean

"scripts": {
  "dev": "turbo run dev",
  "lint": "turbo run lint",
  "build": "turbo run build",
  "clean": "turbo run clean",
  ...
},
"devDependencies": {
  ...
  "turbo": "latest"
}

"scripts": {
  "dev": "turbo run dev --filter=\"docs\"",
  ...
},

Documentation in monorepos?

Monorepos vs. Polyrepos in Git

Versioning with monorepos

"dependencies": {
  "@bigstair/core": "1.0.0",
  "@bigstair/map": "1.0.0",
  ...
}

"scripts": {
  ...
  "changeset-create": "changeset",
  "changeset-apply": "changeset version",
  "release": "turbo run build && changeset publish"
},

• create an organization on npm which allows you to publish packages

• npm login on the command line

• use the name of your organization instead of bigstair everywhere in the source code

• verify with yarn install && yarn dev that everything still works as expected

• First, run yarn changeset-create which enables you to create a changelog for changed packages. The prompt walks you through selecting a package (use spacebar), choosing the semver increment (major, minor, patch), and writing the actual changelog. If you check your repository afterward with git status, you will see the changed source code in addition to a newly created changelog file. If packages depend on each other, the linked packages will get a version bump later too.

• Second, if the changelog file is okay, run yarn changeset-apply which applies the changelog and the version to the actual package. You can check again with git status and git diff if everything looks as desired.

• Third, if everything looks okay, go ahead and release the updated packages to npm with yarn release. After the release, veryfy on npm that your new version got published there.

Continuous Integration with monorepos

name: Release
on:
  push:
    branches:
      - main
concurrency: ${{ github.workflow }}-${{ github.ref }}
jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Setup Node.js 16.x
        uses: actions/setup-node@v2
        with:
          node-version: 16.x
      - name: Install Dependencies
        run: yarn install
      - name: Create Release Pull Request or Publish to npm
        id: changesets
        uses: changesets/action@v1
        with:
          publish: yarn release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Monorepo Architecture

Example: Monorepos as Incubators

FAQs

Follow me on GitHub 🫱:

nooobcoder - Overview

🇮🇳n coder, who considers codes as gems. Blog: nooobcoder-blog.vercel.app 🎓 @LPU (Lovely Professional University) 💻 for @supabase - nooobcoder

https://github.com/nooobcoder

 

---