How to use bun link?

bun link is a powerful command-line tool in the Bun ecosystem that allows developers to efficiently test and develop local packages within other projects without needing to publish them.

Understanding Bun Link for Local Development

bun link creates symbolic links (symlinks) between your local package directories, enabling you to test changes in a dependent project instantly. This eliminates the need to repeatedly publish and install private packages during development, streamlining your workflow. It's particularly useful when you're developing a library or component package and simultaneously building an application that consumes it.

The Two Steps of Using Bun Link

Effectively using bun link involves a two-part process: first, registering your package to be linkable, and then linking it into a consuming project.

Step 1: Registering Your Local Package

To make a package available for linking, you must first register it. This tells Bun that your package is ready to be used by other local projects.

Action: Navigate to the root directory of the package you want to link (e.g., your utility library or component package).

Command:

cd path/to/your/my-awesome-package
bun link

Explanation: When you run bun link in a local directory without any arguments, Bun registers the current package in a global store. This action marks the package as "linkable," making it accessible by its name for other projects to link against.

Step 2: Linking the Package into Another Project

Once your package is registered, you can link it into any project that depends on it.

Action: Go to the root directory of the project where you want to use your registered local package. This is often an application that consumes your library.

Command:

cd path/to/your/my-application
bun link my-awesome-package

Explanation: Running bun link <package-name> in a target project tells Bun to find the globally registered my-awesome-package. It then creates a symlink in your target project's node_modules directory, pointing directly to the original local my-awesome-package directory. This means your application will use the code from your local development version, and any changes you make in the original package are immediately reflected in the consuming project without reinstallation.

Practical Example: Developing a Component Library

Let's illustrate with a common scenario where you are building my-ui-components (a component library) and want to use and test it within my-webapp (an application).

Prepare the Component Library:
First, make your component library linkable by navigating to its directory and running bun link.
```
# In your component library's directory
cd ~/projects/my-ui-components
bun link
```
This registers my-ui-components in Bun's global store.
Use in Your Web Application:
Next, link the registered component library into your web application.
```
# In your web application's directory
cd ~/projects/my-webapp
bun link my-ui-components
```
Now, when your my-webapp project runs, node_modules/my-ui-components will be a symbolic link to ~/projects/my-ui-components. You can import components from your library in my-webapp and instantly see changes as you develop my-ui-components.

Managing Links: Unlinking Packages

When you're finished developing or want to revert to a published version of a package, you can unlink it.

Unlinking from a Project

Action: In the project where the link was created.

Command:

cd path/to/your/my-application
bun unlink my-awesome-package

Explanation: This command removes the symlink from node_modules in the current project. Bun will then install the package from your configured registry (e.g., npm) if it's listed as a dependency in your package.json.

Unregistering a Global Package

Action: In the original package's directory.

Command:

cd path/to/your/my-awesome-package
bun unlink

Explanation: Running bun unlink without arguments in the package directory removes it from Bun's global link store. Other projects will no longer be able to link to this local version of the package.

Benefits of Using Bun Link

bun link offers several advantages for efficient development workflows:

Instant Feedback: Changes made in your local package are immediately available in the consuming project, significantly accelerating the iteration and debugging process.
Simplified Local Testing: Test your package's integration and functionality within a real-world application without the overhead of publishing or managing complex local file: dependencies.
Real-world Environment: Develop and test your package in an environment that closely mimics how it will be consumed once published, ensuring better compatibility.
Cross-Project Development: Easily manage dependencies between multiple local projects, which is ideal for monorepo-like structures or developing interconnected applications and libraries.

Summary of Bun Link Commands

Command	Location (Context)	Purpose
`bun link`	Root of the source package	Registers the current package globally, making it linkable.
`bun link <package-name>`	Root of the target project	Creates a symlink to the registered package in `node_modules`.
`bun unlink <package-name>`	Root of the target project	Removes the symlink and reinstalls the package from the registry.
`bun unlink`	Root of the source package	Deregisters the package from Bun's global link store.

For more detailed information, refer to the official Bun documentation.