pnpm & parcel monorepo test

A repository for trying a JS/TS npm library monorepo setup using pnpm as package manager and parcel as a build tool.

Development prerequisites:

• Node v16+
• pnpm

Tech Stack

This is an overview of the most important components of this monorepo's tech stack

• pnpm -- package and monorepo workspace manager
• Parcel -- build tool
• Jest / ts-jest -- Unit testing framework
• TypeScript / tsc -- TypeScript type checking
• TypeScript ESLint -- linting
• Prettier -- code formatter
• fliegdoc -- documentation generator
• GitHub Actions -- CI pipeline
• Renovate -- Dependency Update Management

Usage

Setting up the development environment

Install the dependencies:

pnpm install

• automatically runs recursively for the workspace, cf. https://pnpm.io/cli/install
• Alias: pnpm i
• npm ci-equivalent: pnpm i --frozen-lockfile (automatically true in CI environment)

You can also run pnpm install when anything about your dependencies becomes out of date to fix it back up.

Dependency Management

Installing dependencies to packages

Run commands in the package's directory:

External dependencies

pnpm add [-D] @fliegwerk/logsemts

Other packages from monorepo

pnpm add [-D] --workspace [package-name]

• --workspace ensures that it is installed from the workspace directory.
• by default installs as workspace:^[version]. I recommend adjusting this to workspace:^ afterwards to make it an easier workflow for updates (this "version specifier" gets replaced automatically with the correct version on publish)

Installing development dependencies to root

In root directory:

pnpm add -D -w @parcel/core

• -w "enables" running this in the workspace root (otherwise forbidden to ensure that you don't accidentally install it in the workspace root)

During Development

Development flow (watching for changes and re-building)

In root directory:

pnpm watch

Testing packages manually (REPL)

Install all pacakges in the workspace root (like the development dependencies, but without the -D argument). Then, simply run node in the root directory, and you can require() all packages.

Testing packages automatically (Jest-based unit tests)

In root directory:

pnpm test

or

pnpm exec jest

Linting and Formatting

Linting with ESLint

In root directory:

pnpm lint

Fix styling issues

In root directory:

pnpm prettier:fix

Check for formatting issues

In root directory:

pnpm prettier:check

Building and publishing

Building packages

In root directory:

pnpm build

Building documentation

In root directory:

pnpm docs

This builds a static documentation page to /docs using fliegdoc.

Publishing packages

After adjusting package versions (TODO: find a way to automate this):

In root directory:

pnpm publish -r

• package versions in subpackages' package.json files get replaced automatically in the published version
• requires a clean git tree

TODO

• Find a way to use conventional commits for automatically adjusting package versions