Bun Fails To Install Local Package In Monorepo: A Fix

Oct 30, 2025 by Admin 54 views

Hey guys! Ever run into a situation where you're working with a monorepo and Bun just refuses to install a local package globally? It's super frustrating, I know! Let's dive into a specific scenario where bun i -g . doesn't quite do what we expect and figure out what's going on.

Understanding the Issue

So, you've got your monorepo all set up. You're cruising along, trying to install a local package using the command bun i -g ., but instead of the sweet success you anticipated, you get... nothing? Or, more accurately, you get a message that seems to indicate something installed, but it's not quite right. Let's break down what's happening and why it's not working as expected.

The Monorepo Setup

First, let's visualize the monorepo structure. Imagine you have a structure like this:

monorepo/
├── package.json
├── bun.lock
└── packages/
    └── package-a/
        └── package.json

Here, package-a is the local package you're trying to install. Inside packages/package-a/package.json, you have something like "name": "@some-scope/some-name". You're in the packages/package-a directory, and you run:

bun i -g .

You expect Bun to install this package globally, making it available for use in other projects or packages. But instead, you see:

❯ bun i -g .
bun add v1.3.1 (89fa0f34)

installed @

[1.00ms] done

It looks like something happened, but it's definitely not what you wanted. So, what gives?

Why `bun i -g .` Fails

The issue here usually stems from how Bun interprets the . in the command bun i -g .. When you use . , you're telling Bun to look at the current directory and treat it as a package to install. However, Bun might not correctly resolve or link this package globally in a monorepo context, especially if there are scoping or naming conventions that it's not fully recognizing.

In simpler terms, Bun might be getting a little confused about where the package should be linked and how it should be named when installing it globally. This is especially true if the package has a scoped name (like @some-scope/some-name). The -g flag is meant to install the package globally, but the local context and monorepo structure can sometimes throw a wrench in the gears.

Potential Solutions and Workarounds

Okay, so we know why it's happening. Now, what can we do about it? Here are a few potential solutions and workarounds to get your local package installed globally.

1. Using `bun link`

One of the most reliable ways to handle this is by using the bun link command. This command is designed to create a symbolic link between your local package and the global node_modules directory. Here's how you can use it:

First, navigate to the directory of your package (in this case, packages/package-a):

cd packages/package-a

Then, run:

bun link

This command creates a global link to your package. Now, in any other project or package where you want to use @some-scope/some-name, you can link it by running:

bun link @some-scope/some-name

This tells Bun to create a symbolic link to the globally linked package. This method ensures that Bun correctly resolves the package and its dependencies within the monorepo context.

2. Publishing to a Local Registry

Another approach, especially useful in larger monorepos or when simulating a production environment, is to use a local registry. Tools like Verdaccio or Nexus can create a local npm registry on your machine. Here’s a basic outline of how to do it:

Set up a local registry:
- Install Verdaccio globally:
```
npm install -g verdaccio
```
- Run Verdaccio:
```
verdaccio
```
This starts a local registry, usually on http://localhost:4873.
Configure npm to use the local registry:
- Set the registry URL:
```
npm config set registry http://localhost:4873
```
Publish the package to the local registry:
- Navigate to your package directory (packages/package-a).
- Publish the package:
```
npm publish
```
Install the package from the local registry:
- In your other projects, install the package:
```
bun install @some-scope/some-name
```

This method ensures that the package is correctly resolved and installed as if it were coming from a remote registry.

3. Using Relative Paths (Less Recommended)

While not ideal, you can use relative paths in your package.json files to reference local packages. However, this approach can be brittle and hard to maintain, especially as your monorepo grows.

In the package.json of a package that depends on @some-scope/some-name, you could specify the dependency like this:

{
  "dependencies": {
    "@some-scope/some-name": "file:../packages/package-a"
  }
}

This tells Bun to install the package directly from the file path. While it can work, it's generally better to use bun link or a local registry for more robust dependency management.

Best Practices for Monorepos with Bun

To avoid these kinds of issues and keep your monorepo running smoothly, here are some best practices to consider:

1. Use a Monorepo Management Tool

Tools like Lerna or Turborepo are designed to manage dependencies and build processes in monorepos. They can help automate tasks like linking local packages and publishing to registries.

2. Keep Dependencies Consistent

Ensure that all packages in your monorepo use consistent versions of dependencies. This can prevent conflicts and ensure that your packages work well together.

3. Automate Linking with Scripts

You can add scripts to your package.json to automate the linking process. For example, you could have a script that runs bun link for all local packages in your monorepo.

4. Regularly Update Bun

Keep your Bun version up to date. The Bun team is constantly improving the tool, and updates often include fixes for issues like this.

Conclusion

Dealing with monorepos can be tricky, but understanding the tools and techniques available can make your life a whole lot easier. When bun i -g . doesn't quite cut it for installing local packages, reach for bun link or a local registry. And remember, a little planning and the right tools can go a long way in keeping your monorepo running smoothly. Happy coding, folks!