bun-link

Purpose

bun link is a package linking command that registers local packages for development use across projects without publishing to npm. It creates symlinks between packages, enabling rapid iteration when developing interdependent packages.

Basic Syntax

# Register current package as linkable
bun link

# Link a registered package into current project
bun link <package-name>

# Unregister a package
bun unlink

How It Works

Step 1: Register the Package

Navigate to your package directory and run:

cd /path/to/my-package
bun link

Output:

bun link v1.3.3 (7416672e)

Success! Registered "my-package"

To use my-package in a project, run:
  bun link my-package

Or add it in dependencies in your package.json file:
  "my-package": "link:my-package"

This registers the package in Bun’s global package registry for linking.

Step 2: Link into Another Project

In your consuming project:

cd /path/to/consuming-app
bun link my-package

This creates a symlink in node_modules/my-package pointing to your local package directory.

Step 3: Add to package.json (Optional)

Use the --save flag to persist the link in package.json:

bun link my-package --save

This adds a special version specifier:

{
  "dependencies": {
    "my-package": "link:my-package"
  }
}

CLI Options

Flag	Alias	Description
`--save`	`-s`	Add package to package.json with link specifier
`--global`	`-g`	Install globally
`--production`	`-p`	Skip devDependencies
`--force`	`-f`	Reinstall all dependencies

Use Cases

Local Monorepo Development

When developing packages within a monorepo:

# In package A
cd packages/core
bun link

# In package B
cd packages/app
bun link core

Testing Before Publishing

Test package changes in a real project before publishing to npm:

# In your package
bun link

# In test app
bun link your-package
# Make changes to package...
# Test immediately in app without republishing

NestJS Module Development

Develop NestJS modules locally alongside applications:

# In shared NestJS module
cd libs/auth-module
bun link

# In NestJS app
cd apps/api
bun link auth-module

Comparison to npm link

Feature	`bun link`	`npm link`
Speed	Fast (native implementation)	Slower
Symlink creation	Direct symlink to local dir	Two-step process
Global registry	Bun-specific	npm global
package.json support	`link:` specifier	Manual setup
Cross-compatibility	Bun projects only	Works with npm/yarn

Unlinking

Remove a linked package:

# Unregister from global registry
cd /path/to/package
bun unlink

# Or remove link from consuming project
cd /path/to/consuming-app
bun unlink my-package

Common Patterns

Workspace Link Alternative

Instead of using Bun workspaces, you can manually link packages:

# Setup
cd package-a && bun link
cd ../package-b && bun link package-a

# Teardown
cd package-a && bun unlink

Development Dependency Linking

Link packages needed only for development:

{
  "devDependencies": {
    "test-utils": "link:test-utils"
  }
}

Troubleshooting

Link Not Found

If bun link <package> fails:

Verify package is registered: bun link in package directory
Check package name matches package.json name field
Ensure you’re using the correct package name (not file path)

Changes Not Reflected

If changes to linked package aren’t appearing:

Restart your development server (some bundlers cache node_modules)
Clear Bun cache: bun pm cache rm
Re-link: bun unlink <package> && bun link <package>

Deployment Issues

Important: Linked packages won’t work in production. Before deploying:

Publish package to npm
Update package.json to use published version
Run bun install to fetch from npm