Dependencies

How to add a library to zap.ts. There is one rule, and it keeps every app on the same version.

A dependency is a library your code uses. zap.ts has two kinds, and each one has its own rule.

The one rule

Never write a version number in a package.json file.

Every version lives in one file instead: pnpm-workspace.yaml. That list is called the catalog.

Why the catalog exists

zap.ts holds six apps and fourteen packages. Without the catalog, the same library could sit at three different versions in three different folders.

That causes two problems. Your app ships the same code twice, so it is bigger than it needs to be. And a bug appears in one app but not another, which is very hard to find.

With the catalog, you upgrade a library in one line, and every app moves together.

Adding a library from outside

Say you want to add date-fns.

Step 1. Add the version to the catalog in pnpm-workspace.yaml:

catalog:
  date-fns: ^4.1.0

Step 2. In the package.json of the package that needs it, write catalog: where the version would normally go:

{
  "dependencies": {
    "date-fns": "catalog:"
  }
}

Step 3. Install:

pnpm install

catalog: means “whatever version the catalog says”. pnpm reads the catalog and fills it in.

Using a package from inside zap.ts

When one package in zap.ts uses another, the rule is different. Write workspace:*:

{
  "dependencies": {
    "@zap-ts/database": "workspace:*"
  }
}

workspace:* means “the copy in this repository”. pnpm links the folder directly. It does not download anything.

This is why a change you make in packages/database shows up in your app at once, with no publishing step.

Upgrading

Change the version in the catalog. Then run pnpm install.

Every package that wrote catalog: now uses the new version. You did not have to find them all.

A summary

Related

• Project structure — which folders exist and why
• Adding a package — create a new shared package
• Conventions — the other rules the codebase follows