From 5da9c78fc47791441b2dd714a1b88801260af0a2 Mon Sep 17 00:00:00 2001
From: Andrei Borza <andrei.borza@sentry.io>
Date: Mon, 19 Oct 2026 11:17:45 +0200
Subject: [PATCH] docs: Add guide for testing SDK packages with pnpm link

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CONTRIBUTING.md         |  2 +-
 docs/using-pnpm-link.md | 67 +++++++++++++++++++++++++++++++++++++++++
 docs/using-yalc.md      |  2 +-
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/using-pnpm-link.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 617cb3a77702..c65ca5d97765 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ upgrading.
 
 To test local versions of SDK packages, for instance in test projects, you have a couple of options:
 
-- Use [`pnpm link`](https://pnpm.io/cli/link) to symlink your package to the test project.
+- Use [`pnpm link`](./docs/using-pnpm-link.md) to symlink your package to the test project.
 - Use [`yalc` to install SDK packages](./docs/using-yalc.md) as if they were already published.
 - Run `build:tarball` in the repo and `pnpm add ./path/to/tarball.tgz` in the project.
 
diff --git a/docs/using-pnpm-link.md b/docs/using-pnpm-link.md
new file mode 100644
index 000000000000..15aaef6890e2
--- /dev/null
+++ b/docs/using-pnpm-link.md
@@ -0,0 +1,67 @@
+# Using `pnpm link` for Local SDK Testing
+
+[`pnpm link`](https://pnpm.io/cli/link) symlinks a local SDK package into a test project. Changes are available in the
+test project after a rebuild, without a publish step. For packages where linking causes problems (e.g. SvelteKit or
+Angular), use [`yalc`](./using-yalc.md) instead.
+
+## Building packages
+
+Build the SDK package and the packages it depends on. Run this in the root of the repo:
+
+```sh
+pnpm run build:dev:filter @sentry/node # or any other SDK package
+```
+
+## Linking packages
+
+In your test project, run `pnpm link` with the path to the SDK package:
+
+```sh
+pnpm link /path/to/sentry-javascript/packages/node
+```
+
+You only need to link the SDK package that your project imports. Its dependencies (e.g. `@sentry/core`) resolve from
+the monorepo, so they are also the local versions. If your project also imports a dependency directly (e.g.
+`@sentry/core`), that import still uses the version from the registry. Link that package too.
+
+`pnpm link` adds a `link:` override to the `pnpm-workspace.yaml` of your test project. If the file does not exist,
+`pnpm link` creates it. Do not commit this override.
+
+## Updating packages
+
+The link points to the `build/` folder of the package. After a code change, rebuild the package and restart your test
+project. You do not need to link again.
+
+```sh
+# in the package you changed, e.g. packages/core
+pnpm run build:transpile
+```
+
+## Unlinking packages
+
+In your test project, run `pnpm unlink` with the package name. This removes the `link:` override and installs the
+registry version again.
+
+```sh
+pnpm unlink @sentry/node
+```
+
+In pnpm 10, `pnpm unlink` shows "Nothing to unlink" and does not remove the override. Remove the override
+for the package from `pnpm-workspace.yaml` manually, then run `pnpm install`.
+
+## Troubleshooting
+
+### My test project still uses the registry version
+
+Make sure that `node_modules/@sentry/node` in your test project is a symlink to the monorepo:
+
+```sh
+ls -la node_modules/@sentry/node
+```
+
+If you run Node.js or your bundler with `--preserve-symlinks`, dependencies resolve from the `node_modules` of your
+test project and not from the monorepo. Do not use this flag.
+
+### My test project uses Vite and I still don't see changes
+
+Vite pre-bundles and caches dependencies for dev builds. Run `vite dev --force` to clear the cache.
diff --git a/docs/using-yalc.md b/docs/using-yalc.md
index f89d748a72e0..f95465aa45eb 100644
--- a/docs/using-yalc.md
+++ b/docs/using-yalc.md
@@ -1,7 +1,7 @@
 # Using `yalc` for Local SDK Testing
 
 [Yalc](https://github.com/wclr/yalc) is a simple local dependency repository which we can use to work with local
-versions of our SDKs. This is a good alternative to `npm|pnpm link` for packages where linking is problematic (e.g.
+versions of our SDKs. This is a good alternative to [`pnpm link`](./using-pnpm-link.md) for packages where linking is problematic (e.g.
 SvelteKit or Angular).
 
 Here's how to set up and use yalc: