Linking in monorepo creates unwanted original copy in packages/apps

[dominicinkfnd]

If I run at the root:
bun link my-package

It correctly replaces the my-package in the root.

However it also then adds the original my-package copies to the packages/apps:

./package.json
{
  "catalog": {
    "my-package": "1.0.3"
  }
}

./apps/my-app/package.json
{
  "depedencies": {
    "my-package": "catalog:",
  }
}

After running bun link my-package at the root:

node_modules/my-package/ <--- the linked package, what we want!
apps/my-app/node_modules/my-packages/ <--- the non-linked package! There wasn't even a node_modules here before

So when I start my-app it still loads the unlinked package.

How can I stop that from happening?

[KeepALifeUS]

Solution: Bun Link in Monorepo

The issue is that Bun hoists the linked package to root but still resolves the catalog version for nested workspaces.

Fix 1: Link in the specific workspace

cd apps/my-app
bun link my-package

Fix 2: Use workspace protocol instead of catalog

// apps/my-app/package.json
{
  "dependencies": {
    "my-package": "workspace:*"
  }
}

Then link your local development version:

cd packages/my-package
bun link
cd ../../apps/my-app
bun link my-package

Fix 3: Override resolution in root package.json

{
  "overrides": {
    "my-package": "link:./path/to/local/my-package"
  }
}

Then run bun install.

Fix 4: Delete nested node_modules and reinstall

rm -rf apps/my-app/node_modules
bun link my-package
bun install

Why this happens

Bun catalog resolution happens before link resolution. The workspace still tries to resolve from catalog, creating the nested copy. Using workspace protocol or overrides bypasses catalog lookup.

[MILLERMARRU]

The root of it: catalog: and workspace: are different protocols doing different jobs, and only one of them is symlink-aware. catalog: just resolves to a version string pinned in the root catalog/catalogs table, it's Bun's implementation of pnpm's catalog protocol, and it participates in normal registry/version resolution. workspace:*, by contrast, is what tells Bun's installer that a dependency is a local package to be resolved by path rather than fetched as a tarball, and that's the mechanism bun link actually hooks into.

So when apps/my-app/package.json says "my-package": "catalog:", bun install sees a version constraint and is free to satisfy it however normal resolution would, including placing a real copy in apps/my-app/node_modules if the hoisting result from your root-level bun link doesn't already satisfy that nested lookup. The root symlink and the catalog-driven install aren't really in conflict, they're just two resolution mechanisms that don't know about each other.

Given that, the fix is to make the package you're actively developing use workspace:* instead of catalog:, since workspace: is the protocol that actually ties resolution to your local path rather than to a version:

// apps/my-app/package.json
{
  "dependencies": {
    "my-package": "workspace:*"
  }
}

Then bun link my-package (or just a normal bun install with the workspace already declaring it locally) resolves consistently everywhere, no per-app relinking needed. Keep catalog: for the dependencies you're not actively developing against locally, that pin-a-version behavior is exactly what you want there. It's only the package you're linking that needs to come out of the catalog and into workspace:*.

[gitsult4n]

bun link works like npm link/yarn link — it's a two-step process. bun link my-package at the package root only registers the global link. Each consuming workspace package still needs to explicitly consume it by running bun link my-package from inside that workspace (apps/my-app) too. The root-level link doesn't automatically propagate into nested workspace installs, especially with catalog: references — those still resolve/install normally unless the consuming package opts into the link itself.