bunenv

A version manager for Bun JavaScript runtime, inspired by tools like rbenv and nvm.

Features

• 🚀 Install and manage multiple Bun versions
• 🔄 Switch between versions globally or per project
• 🔍 Automatic version detection using .bun-version files
• 🛠️ Shell integration for seamless version switching
• 🐚 Support for bash, zsh, and fish shells
• 🍺 Homebrew installation support

Development Status

The project is now ready for initial release with all core functionality in place:

• ✅ Core modules: Version resolver, Path utilities, and Configuration
• ✅ Version manager: Installation, listing, and management of Bun versions
• ✅ Shim generator: Creation and management of shims for version switching
• ✅ CLI Commands: All commands are implemented and working
• ✅ Testing: Unit tests passing, direct function tests implemented, integration tests in progress
• ✅ Documentation: Comprehensive documentation with guides and examples
• ✅ Distribution: npm packaging and CI/CD workflows configured

Current focus

• Ongoing testing improvements
• Community feedback and bug fixes
• Additional features based on user needs

Documentation

• Shell Integration Guide - Detailed guide on setting up and troubleshooting shell integration

Examples

• Project-Specific Version Management - How to manage Bun versions per project
• Global Version Management - Setting up and working with global Bun versions
• Temporary Version Switching - Temporarily using different Bun versions

Installation

Prerequisites

• Node.js 16+ or Bun
• UNIX-like operating system (macOS, Linux) or Windows with WSL

Using Homebrew (macOS and Linux)

The easiest way to install bunenv on macOS or Linux is via Homebrew:

# Install bunenv via Homebrew
brew install jonathanphilippou/tap/bunenv

# Verify the installation
bunenv --version

Quick Install (Recommended)

Alternatively, you can install bunenv using our installer script:

# Using curl
curl -o- https://raw.githubusercontent.com/jonathanphilippou/bunenv/main/install.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/jonathanphilippou/bunenv/main/install.sh | bash

This script will install bunenv and set up shell integration automatically.

Install via npm

npm install -g bunenv

# Then set up shell integration
bunenv init >> ~/.bashrc  # or your appropriate shell config file
source ~/.bashrc

Install via Bun

bun install -g bunenv

# Then set up shell integration
bunenv init >> ~/.bashrc  # or your appropriate shell config file
source ~/.bashrc

Manual installation

1. Clone the repository:

git clone https://github.com/jonathanphilippou/bunenv.git
cd bunenv

2. Install dependencies:

npm install
# or if you have Bun installed
bun install

3. Build the project:

npm run build
# or
bun run build

4. Link the binary:

npm link
# or
bun link

5. Set up shell integration:

bunenv init >> ~/.bashrc
# Or for zsh
bunenv init --shell zsh >> ~/.zshrc
# Or for fish
bunenv init --shell fish >> ~/.config/fish/conf.d/bunenv.fish

6. Restart your shell or source the configuration file:

source ~/.bashrc
# Or for zsh
source ~/.zshrc

Quick Start

Installing Bun versions

# Install a specific version
bunenv install 1.0.0

# List installed versions
bunenv list

Setting global version

# Set the global Bun version
bunenv global 1.0.0

# View current global version
bunenv global

Setting local version

# Set the local Bun version for the current directory
bunenv local 1.0.0

# View current local version
bunenv local

Temporary version switching

# Spawn a new shell with a specific Bun version
bunenv shell 1.0.0

Command Reference

bunenv install <version>

Install a specific version of Bun.

Options:

• -f, --force: Force reinstall if the version is already installed

bunenv list

List all installed Bun versions.

Aliases: ls

Options:

• -a, --all: Show all versions, including system installations

bunenv global [version]

Set or show the global Bun version.

bunenv local [version]

Set or show the local Bun version for the current directory.

bunenv shell <version>

Spawn a new shell using the specified Bun version.

bunenv version

Show the current active Bun version.

Options:

• -v, --verbose: Show detailed version information

bunenv rehash

Rebuild Bun shim executables.

bunenv init

Configure shell integration for bunenv.

Options:

• -s, --shell <type>: Specify shell type (bash, zsh, fish)

How it Works

bunenv works by creating a directory of shims, which map to the commands for the selected Bun version. When you run a shim, bunenv determines which Bun version to use by checking:

1. The BUNENV_VERSION environment variable
2. A .bun-version file in the current or parent directories
3. The global Bun version set with bunenv global

Version Resolution

The version resolution follows this priority order:

1. The BUNENV_VERSION environment variable
2. The .bun-version file in the current directory
3. The .bun-version file in parent directories (searching up to root)
4. The global version set with bunenv global

Directory Structure

$HOME/.bunenv/
├── versions/         # Bun versions
│   ├── 1.0.0/
│   │   └── bin/
│   │       └── bun
│   └── 1.0.1/
│       └── bin/
│           └── bun
├── shims/            # Command shims
├── version           # Global version file
└── .bun-version      # Local version file (in project directories)

Development

Setup

git clone https://github.com/yourusername/bunenv.git
cd bunenv
bun install

Testing

bun test          # Run all tests
bun test:unit     # Run unit tests
bun test:component # Run component tests
bun test:integration # Run integration tests

Building

bun run build

Project Structure

The project is structured into several key modules:

• src/core/ - Core utilities (paths, config, environment)
• src/resolvers/ - Version resolution logic
• src/versions/ - Version management and installation
• src/shims/ - Shim generation and management
• src/cli/ - CLI commands and utilities
• src/utils/ - Shared utility functions

Testing Strategy

We follow a test pyramid approach:

• Unit Tests: Test individual functions in isolation
• Component Tests: Test interactions between modules
• Integration Tests: Test end-to-end functionality

Contributing

We welcome contributions of all kinds! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/bunenv.git
3. Install dependencies: bun install
4. Create a branch for your contribution: git checkout -b my-feature-branch

Development Workflow

1. Make your changes
2. Run tests: bun test
3. Format your code: bun run format
4. Commit your changes following conventional commits
5. Push to your fork and submit a pull request

Homebrew Formula Development

If you're working on improving the Homebrew integration:

1. Read the Homebrew documentation to understand the current implementation
2. Test any changes locally with brew install --build-from-source ./homebrew/bunenv.rb
3. Update the formula using the automated script: bun homebrew:update

Code Standards

• Follow TypeScript best practices
• Write tests for new functionality
• Document your code with JSDoc comments
• Keep commits focused and descriptive

Documentation

When adding or changing features, please update the relevant documentation:

• README.md for general usage information
• Specific documentation files in the docs/ directory

For detailed information on specific topics, check out these resources:

• Contribution Guidelines
• Code of Conduct
• Homebrew Integration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by rbenv and nvm
• Built with TypeScript and Bun
• Thanks to all contributors

Using npm

npm install -g bunenv

Using bun

bun install -g bunenv

Diagram:

+---------------------------------------------+
|                   User                      |
+----------------------+----------------------+
                       |
                       | (runs command: e.g., bun --version)
                       v
+---------------------------------------------+
|                 PATH lookup                 |
|   (~/.bunenv/shims takes precedence)        |
+----------------------+----------------------+
                       |
                       | (finds shim first)
                       v
+---------------------------------------------+
|               ~/.bunenv/shims/bun           |  <---- Shim Script (Bash)
|                                             |       Intercepts all 'bun' calls
+----------------------+----------------------+
                       |
                       | (looks for version)
                       v
+---------------------/ \---------------------+
|  Version Resolution Process                 |
|                                             |
|  1. Check BUNENV_VERSION env var            |
|  2. Look for .bun-version file (local)      |
|  3. Check package.json engines.bun          |
|  4. Check ~/.bunenv/version (global)        |
|                                             |
+----------------------+----------------------+
                       |
                       | (selects version)
                       v
+---------------------------------------------+
|      ~/.bunenv/versions/{version}/bin/bun   |  <---- Actual bun binary
+---------------------------------------------+
          |                        |
          v                        v
+-------------------+   +----------------------+
| bunenv CLI Tool   |   | User's Bun Commands  |
| (bunenv install)  |   | (managed by version) |
+-------------------+   +----------------------+

+---------------------------------------------+
|            Core Components                  |
+---------------------------------------------+
|                                             |
|  ~/.bunenv/                                 |
|  ├── shims/                                 |
|  │   └── bun           (shim executable)    |
|  ├── versions/                              |
|  │   ├── 1.0.0/        (installed version)  |
|  │   │   └── bin/                           |
|  │   │       └── bun   (actual executable)  |
|  │   └── 1.0.22/       (another version)    |
|  │       └── bin/                           |
|  │           └── bun                        |
|  └── version           (global version file)|
|                                             |
+---------------------------------------------+

+--------------+       +--------------------+
| bunenv CLI   | <---> | Version Management |
|              |       | (install/list/etc) |
+--------------+       +--------------------+
       |
       v
+-------------------------------+
| Commands:                     |
| - bunenv install <version>    |
| - bunenv global <version>     |
| - bunenv local <version>      |
| - bunenv rehash               |
| - bunenv list                 |
| - bunenv version              |
| - bunenv shell <version>      |
| - bunenv init                 |
+-------------------------------+