JavaScript and TypeScript Monorepos
Learning Paths:
Table of Contents
Introduction
Introduction
Mike North defines monorepos as many related packages that are all located within the same git repository, explains that the main project of the course will be to build a Slack application, and gives an overview of the different topics covered in this course.
Repo Walkthrough & Yarn Workspaces
Mike gives a tour of the course repository, explains that the source code for this course is the base application code, and that the course focuses more on configuring projects, and setting up build scripts.
Composite TypeScript Project
Composite TypeScript Project
Mike demonstrates how to set up a basic tsconfig file, sets up a composite project by updating the ts.config file, and explains that the tsconfig.tsbuildinfo is a file that tracks information about the various builds within an application.
Cleaning Output & rimraf
Mike creates another tsconfig file that builds the necessary tools for various packages, and explains that when working with multiple projects in monorepoes each one refers to the other through a dist folder. Installing utilities outside of the packages folder for development purposes only is also discussed in this segment. The purpose of building configurations in different folders is to avoid the use of complex libraries.
Volta Executable Version Q&A
Mike answers questions about Volta and TypeScript versions varying from one working directory to another, and explains that even if there is a global TypeScript version, each working directory can have its own TypeScript version. Volta is a tool that manages JavaScript command-line tools, such as Node, npm, and Yarn. It uploads the correct version for each working directory to avoid bugs, and development or building related issues.
Adding Tests with Jest & Babel
Mike adds testing to the monorepos using Jest, builds a Babel configuration in the packages folder to ensure one source of truth for the configuration, and copies the configuration to both the types and utils folder. Jest allows developers to have one unique solution that solves issues for all packages. In this segment, a Yarn script is defined for the purpose of running the Yarn test command within any package of the workspace.
Yarn 2 and Dependencies Q&A
Mike explains that Volta allows developers to install a specific version of Yarn and Node even if other versions of Node and Yarn are used outside of the monorepository, covers the main differences between Yarn 1 and Yarn 2, and explains the main differences between having Jest as a workspace dependency vs. a package dependency.
Linting & Centralizing Builds
Linting & ESLint Setup
Mike explains that linting files, such as eslintrc, are expected to be in the workspace root by editors like VS Code, therefore ESlint is a workplace version dependency. A lint task is added to each package in the workspace to provide the same linting rules across packages.
Lerna Config & Versioning
Mike introduces Lerna, a library that provides tooling to manage multi-repository structure inside a single repository by separating out subsets of the repository into their own “sub” repositories, and demonstrates where to add the Lerna config file within a workspace.
Lerna Commands
Mike explains that Lerna gives developers the ability to run tests concurrently, and reviews the most useful Lerna commands, namely Lerna link, bootstrap, and run.
Lerna Q&A
Mike answers questions about having local dependencies vs. having workspace root dependencies within a monorepo, the right version to use for a specific package within the workspace, and whether or not to use the Bolt library, a library that resembles Lerna.
Scripty
Mike explains that it is best practice when building a monorepo to link, test, and build each repository the same way, in other words, to centralize the build script, and explains how and when to use scripty. Scripty is a CLI tool that allows developers to extract npm scripts into their own files without changing the command used to run them.
Scripty Monorepo Configuration
Mike demonstrates how to configure scripty to create a workspace folder script and a folder where packages can find scripts, and modifies the package.json configurations so that tests, linting and building within a monorepo all use scripty. This methodology reduces the amount of shell scripts that need to be kept up to date.
Conventional Commits & CommitLint
Changelogs
Mike demonstrates how to add a Husky configuration that ensures that commits are in alignment with a specific convention the developer is trying to set up. How to use Husky to add additional git hooks is also discussed in this segment. Husky is a package that prevents bad commits in a given repository.
Validating Commit Messages
Mike demonstrates how to use the Husky package to check that commits follow a specific convention, and demonstrates how to write valid commit messages.
Lerna Commands for Release Management
Mike demonstrates how to use Lerna to bump the version of packages changed since the last release of a monorepository, and walks the students through the changelog generated by Lerna.
commitLint Q&A
Mike answers questions about the commitlint conventions, about the various layers of configurations within commitlint, and demonstrates a situation when a commitlint flag commits that do not fall within the configuration standards.
Publishing with Verdaccio
Mike introduces Verdaccio, a local npm proxy, explains that it allows developers to track internal package changes and publish internal package changes easily without having to keep track of each individual dependency version.
Dependencies
Internal Dependencies
Mike demonstrates how to use Lerna so that the UI and folders both dependent on types and utils by creating a local version of both the types and utils packages, and makes data dependent on UI since in a given application the UI makes requests to the data layer.
Ensuring that Dependencies Work
Mike demonstrates how to test that each new dependency functions the correct way, and explains how to modify the amount of concurrent tasks so that the data, types, UI, and utils packages run at the same time. It is important to know that although developers can allow multiple packages to run at the same time, Lerna runs packages by layers, meaning it runs the packages upon which other packages depend first.
Adding a Scoped Start Script
Mike demonstrates how to add a start script to an application using bash, and how to use Lerna to make starting an application easier.
Watch Output
Mike demonstrates how to implement a watch script that reports changes and errors made within an application during development. This allows developers to easily track errors before pushing code.
Documentation
API Extractor Setup
Mike explains that the more sophisticated an application gets, the more a developer needs to write proper documentation and demonstrates how to setup the API extractor. It is best practice to have a copy of the api-extractor.json in each package of a monorepo.
API Reporting Docs with API Extractor
Mike creates an api-report script, walks students through the various API reports that concisely summarize the API signatures, and demonstrates how to build API docs for each important package within a monorepo.
Large Team Monorepos Q&A
Mike answers questions about how a large team would contribute to a monorepo, and implement high quality bug fixes within a monorepo. Best practices that a team should apply when working on a monorepo are also discussed in this segment.
Adding API Documentation
Mike finishes the course by adding API documentor, and demonstrates how to debug the API documentation.
Rendering API Documentation
Mike pushes the API documentation code, visualizes the API documentation in GitHub, and explains that the API documenter package allows developers to write documentation in HTML instead of Markdown only.
