bun link: Link a Local Package
bun link symlinks a local package into another project so you can develop a library and its consumer together.
bun link mirrors npm link: register a package globally from its own directory, then link it into a consumer. It is a development convenience and almost never belongs in CI.
What it does
Run bun link inside a package directory to register it globally by its package.json name. Then run bun link <name> in a consuming project to symlink the registered package into that project's node_modules, so changes are picked up without publishing.
Common usage
# in the library directory
cd my-lib && bun link
# in the consumer project
cd ../my-app && bun link my-lib
# undo
bun unlink my-libOptions
| Flag | What it does |
|---|---|
| (no args, in package dir) | Register this package globally for linking |
| <name> | Link the named globally-registered package into this project |
| bun unlink <name> | Remove the link |
In CI
Do not rely on bun link in CI; the global link does not exist on a fresh runner, so a build that imports a linked package will fail with a missing module. For monorepos, use workspaces (the workspaces field in package.json) instead, which Bun resolves automatically during bun install.
Common errors in CI
"Cannot find module \"my-lib\"" in CI after working locally is the classic sign a dependency was satisfied by a local bun link that does not exist on the runner; publish the package, use a file: dependency, or switch to workspaces. "error: package not linked" means you ran bun link <name> before registering the library with a bare bun link.