element-call/docs/linking.md

Quickstart guide

Run:

./scripts/setup-linking.sh

Read the script output:

Setup complete.
Update: .links.cjs to your liking
Run: 'pnpm links:on' to test your .links.cjs
Run: 'git commit' with links enabled to test the git pre-commit hook.
Run: 'pnpm links:off' to be able to commit again
Run: 'git config --local core.hooksPath ""' to allow committing with linking (not recommended)
Run: 'rm links.cjs' & 'git config --local core.hooksPath ""' to fully revert what this script did

Developing with linked packages

If you want to make changes to a package that Element Call depends on and see those changes applied in real time, you can create a link to a local copy of the package. pnpm has a command for this (pnpm link), but it's not recommended to use it as it ends up modifying package.json with details specific to your development environment.

Instead, create a file named .links.cjs in the Element Call project directory (or run ./scripts/setup-linking.sh to create a template), listing the names and paths of any dependencies you want to link. For example:

// Packages to link to local checkouts
module.exports = {
  "matrix-js-sdk": "../your/path/matrix-js-sdk",
  "matrix-widget-api": "../your/path/matrix-widget-api",
};

Then run pnpm links:on. (this will activate the pnpm file + run pnpm install to setup the linking)

Hooks

Changes in .links.cjs will also update pnpm-lock.yaml when pnpm install is executed. The lockfile will then contain the local version of the package which would not work on others dev setups or the github CI.

One always needs to remove the pnpm readPackage script (the .pnpmfile.cjs) and run:

pnpm install

before committing a change.

To make this less of a foot gun we added a git hook. A pre-commit hook will check if linking is currently used. If it detects a .pnpmfile.cjs file it will abort the commit with an explanatory message. You will then need to run pnpm links:off and commit again.

To activate the hooks configure git with (when using the setup script (./scripts/setup-linking.sh) this is already done):

git config --local core.hooksPath .githooks

This will add the hook path for this repository only to .gihooks. which is a tracked (by git) folder containing the pre-commit hook.

Testing against a matrix-js-sdk branch in CI

Linking covers local development. In CI, scripts/layered.sh plays the same role for matrix-js-sdk: after the usual frozen install, scripts/fetchdep.sh looks for a matrix-js-sdk branch with the same name as the pull request's head branch (in the fork first, when the pull request comes from one). If there is one, it is cloned, packed and installed over the locked version. If there is none, the install stays as pnpm-lock.yaml pins it.

This means a change that needs a not yet merged matrix-js-sdk change can be tested by giving both branches the same name. This mirrors how element-web tests against matrix-js-sdk. Once the matrix-js-sdk branch is merged and deleted, the pull request falls back to the lockfile and needs a lockfile bump to stay green, which is also what keeps main consistent after the merge.

Background

Information, why this approach is used can be found in the linking concept reasoning document.