Bundlebun

https://github.com/yaroslav/bundlebun
Admin
Bundlebun bundles the Bun JavaScript runtime, package manager, and build tool directly into your...
Tokens:8,435
Snippets:80
Trust Score:9.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Development Environment

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Commands to set up the development environment, including installing gems, fetching a local Bun build for tests, and running tests.

```sh
bin/setup
```

```sh
rake bundlebun:download
```

```sh
rake rspec
```

--------------------------------

### Install Bundlebun Gem

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Add the bundlebun gem to your Gemfile and run `bundle install` followed by `rake bun:install` to install binstubs and auto-configure integrations. This task also creates the `bin/bun` executable.

```ruby
# Gemfile — place after other frontend-related gems so integrations are auto-detected
gem "vite_rails"   # optional
gem "bundlebun"
```

```sh
bundle install
rake bun:install
# => Installs bin/bun (and bin\bun.cmd on Windows)
# => Auto-detects vite-ruby, cssbundling-rails, jsbundling-rails
# => Offers to migrate package.json scripts and Procfile entries

bin/bun --version
# => 1.2.5
```

--------------------------------

### Add BundleBun and Install Bun

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Add the bundlebun gem to your Gemfile and run the install rake task. This sets up the bin/bun binstub and detects integrations.

```ruby
gem "bundlebun"
```

```sh
bundle add bundlebun
rake bun:install
```

--------------------------------

### Run Bun Commands via Binstub

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Execute Bun commands directly using the generated bin/bun binstub. This is the recommended way to interact with Bun after installation.

```sh
bin/bun install
bin/bun add postcss
bin/bun run build
```

--------------------------------

### Check Bun Version

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Verify the installed Bun version using the command-line interface after installation.

```sh
bundle add bundlebun
rake bun:install
bin/bun --version
```

--------------------------------

### Bootstrap cssbundling-rails and jsbundling-rails

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Commands to bootstrap cssbundling-rails and jsbundling-rails, including installing the gems and configuring JavaScript builds with Bun.

```sh
# Bootstrap cssbundling-rails
bundle add cssbundling-rails
bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass]
```

```sh
# Bootstrap jsbundling-rails
bundle add jsbundling-rails
bin/rails javascript:install:bun
```

```sh
# Ensure bundlebun integration
rake bun:install:bundling-rails
```

--------------------------------

### Install Vite Ruby Integration

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Run the `rake` task to install the vite-ruby integration, which ensures a `bin/bun` binstub and creates a `bin/bun-vite` binstub for build scripts.

```sh
rake bun:install:vite
```

--------------------------------

### Bundlebun Rake Tasks

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Provides Rake tasks for installing Bun, integrating with frameworks, and running Bun commands.

```sh
# List all available bundlebun tasks
rake -T bun

# Core install (auto-detects frameworks)
rake bun:install
# => Installs bin/bun binstub
# => Detects vite-ruby, cssbundling-rails, jsbundling-rails
# => Offers to migrate package.json and Procfile

# Install binstub only
rake bun:install:bin

# Install cssbundling-rails / jsbundling-rails integration
rake bun:install:bundling-rails

# Install vite-ruby integration (creates bin/bun-vite, updates config/vite.json)
rake bun:install:vite

# Migrate package.json scripts to use bin/bun (interactive, asks for confirmation)
rake bun:install:package

# Migrate Procfile* entries to use bin/bun (interactive)
rake bun:install:procfile

# Run Bun via Rake (note the quotes — required for arguments)
rake "bun[install]"
rake "bun[outdated]"
rake "bun[run build]"
rake "bun[-e 'console.log(2+2)']"
```

--------------------------------

### Run Bun Commands via Rake Task

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Alternatively, use the rake bun[command] task to run bundled Bun commands. This is useful if you cannot install the binstub. Ensure commands with parameters are quoted.

```sh
rake bun[command]
> rake "bun[outdated]"
```

--------------------------------

### Execute Bun Commands with Bundlebun.call

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Use `Bundlebun.call` or its `()` shortcut to execute Bun commands. This method replaces the current Ruby process and never returns.

```ruby
Bundlebun.('install')               # exec: replaces the current Ruby process with Bun
```

```ruby
Bundlebun.call(['add', 'postcss'])  # same thing, array form
```

--------------------------------

### Bundlebun Execution Methods

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

These methods allow you to execute Bun commands directly from Ruby. `Bundlebun.call` and its shortcut `Bundlebun.()` replace the current Ruby process and never return. Use `Bundlebun.system` to run Bun commands and continue executing Ruby code.

```APIDOC
## Bundlebun Execution

### Description
Executes Bun commands. `Bundlebun.call` and `Bundlebun.()` replace the current process. `Bundlebun.system` runs Bun and returns control to Ruby.

### Methods
- `Bundlebun.call(args)`: Executes Bun command, replaces current process.
- `Bundlebun.('command')`: Shortcut for `Bundlebun.call`.
- `Bundlebun.system(args)`: Executes Bun command, returns success status.

### Examples
```ruby
# Execute 'install' and replace the current Ruby process
Bundlebun.('install')

# Execute 'add postcss' using an array argument
Bundlebun.call(['add', 'postcss'])

# Execute 'install' and continue Ruby execution
if Bundlebun.system('install')
  puts 'Dependencies installed!'
end

# Check if a Bun command exited successfully
success = Bundlebun.system('test')
# => true if Bun exited successfully, false or nil otherwise
```
```

--------------------------------

### Bundlebun.system

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Runs Bun as a subprocess using `Kernel.system`, returning control to Ruby after execution. It returns `true` on success, `false` on non-zero exit, and `nil` if execution fails.

```APIDOC
## Bundlebun.system

### Description
Runs Bun as a subprocess using `Kernel.system` and returns control to Ruby. Returns `true` on success (exit 0), `false` on non-zero exit, or `nil` if execution failed. Use this when Ruby code must continue after Bun finishes.

### Method
`Bundlebun.system(args)`

### Parameters
#### Arguments (`args`)
- **args** (String or Array) - Required - The arguments to pass to the Bun executable. Can be a single string or an array of strings.

### Request Example
```ruby
# Simple success check
if Bundlebun.system('install')
  puts 'Dependencies installed!'
else
  puts 'Installation failed'
  exit 1
end

# Array form for arguments with spaces
success = Bundlebun.system(['run', '--bun', 'build'])
puts success ? 'Build succeeded' : 'Build failed'
```

### Response
- **Return Value** (Boolean or nil) - `true` if Bun executed successfully (exit code 0), `false` if Bun exited with a non-zero code, or `nil` if the execution itself failed (e.g., binary not found).
```

--------------------------------

### Run Bun Commands with Bundlebun.system

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Use `Bundlebun.system` to run Bun commands and continue executing Ruby code afterward. It returns true if Bun exits successfully, or false/nil otherwise.

```ruby
if Bundlebun.system('install')
  puts 'Dependencies installed!'
end
```

```ruby
success = Bundlebun.system('test')
# => true if Bun exited successfully, false or nil otherwise
```

--------------------------------

### Run Bun as a subprocess using Bundlebun.system

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Employ `Bundlebun.system` to execute Bun as a subprocess, returning control to Ruby. It returns `true` for success, `false` for non-zero exit codes, and `nil` if execution fails. This is ideal for scripting where Ruby code needs to continue after Bun completes. Arguments can be provided as a string or an array.

```ruby
require 'bundlebun'

# Simple success check
if Bundlebun.system('install')
  puts 'Dependencies installed!'
else
  puts 'Installation failed'
  exit 1
end

# Array form for arguments with spaces
success = Bundlebun.system(['run', '--bun', 'build'])
puts success ? 'Build succeeded' : 'Build failed'

# Chaining operations
steps = ['install', 'run build', 'run test']
steps.each do |step|
  result = Bundlebun.system(step)
  abort "Failed at: bun #{step}" unless result
end
puts 'All steps completed'

# nil means execution itself failed (binary not found, permission error, etc.)
result = Bundlebun.system('test')
case result
when true  then puts 'Tests passed'
when false then puts 'Tests failed'
when nil   then puts 'Could not run Bun'
end
```

--------------------------------

### Execute Bun using Bundlebun.call/exec

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Use `Bundlebun.call` or `Bundlebun.exec` to replace the current Ruby process with Bun. This method is suitable for binstubs and wrappers as it never returns. It accepts arguments as a string or an array. `Bundlebun.call` can also be invoked using the `.()` shorthand. Calls without arguments raise an `ArgumentError`.

```ruby
# bin/bun binstub (generated by rake bun:install)
#!/usr/bin/env ruby
require 'bundler/setup'
require 'bundlebun'

Bundlebun.call(ARGV)
# Ruby process ends here; Bun takes over with the given arguments

# Direct usage examples
Bundlebun.call('outdated')           # string form
Bundlebun.call(['add', 'postcss'])   # array form
Bundlebun.('install')                # .() shorthand

# In a Rake context
task :frontend_install do
  Bundlebun.exec('install')          # alias for .call
end

# Raises ArgumentError — no-argument calls are rejected
begin
  Bundlebun.call
rescue ArgumentError => e
  puts e.message  # => "wrong number of arguments"
end
```

--------------------------------

### Prepend Bundled Bun Directory to PATH

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Automatically prepends the bundled Bun directory to the system PATH. This is idempotent and uses platform-aware separators.

```ruby
require 'bundlebun'

# Already called automatically on gem load:
# Bundlebun.prepend_to_path
# => Bundlebun::Runner.full_directory is prepended to ENV['PATH']

# Check the current PATH
puts Bundlebun::EnvPath.path
# => "/path/to/vendor/bun:/usr/local/bin:/usr/bin:/bin"

# Manually prepend an additional path (idempotent)
Bundlebun::EnvPath.prepend('/custom/tool/dir')
puts ENV['PATH']
# => "/custom/tool/dir:/path/to/vendor/bun:/usr/local/bin:..."

# Platform-aware separator
Bundlebun::EnvPath.separator
# => ":"   (Unix)
# => ";"   (Windows)
```

--------------------------------

### Bundlebun.call / Bundlebun.exec

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Replaces the current Ruby process with Bun, executing it with the provided arguments. This method never returns and is suitable for binstubs. It can be called with string or array arguments.

```APIDOC
## Bundlebun.call / Bundlebun.exec

### Description
Replaces the current Ruby process with Bun using `Kernel.exec`. This method **never returns**. It is the default execution mode used by binstubs. Also callable as `Bundlebun.(args)` using the `.()` shorthand. Raises `ArgumentError` if called without arguments.

### Method
`Bundlebun.call(args)` or `Bundlebun.exec(args)` or `Bundlebun.(args)`

### Parameters
#### Arguments (`args`)
- **args** (String or Array) - Required - The arguments to pass to the Bun executable. Can be a single string or an array of strings.

### Request Example
```ruby
# String form
Bundlebun.call('outdated')

# Array form
Bundlebun.call(['add', 'postcss'])

# Shorthand
Bundlebun.('install')

# Alias
Bundlebun.exec('install')
```

### Error Handling
- Raises `ArgumentError` if called without arguments.
```

--------------------------------

### Bundlebun::Runner Path Utilities

Source: https://context7.com/yaroslav/bundlebun/llms.txt

The `Bundlebun::Runner` class provides utilities for locating the bundled Bun binary and project binstubs. It exposes methods to check for the existence of these files and determine the preferred execution path. Direct instantiation is also possible for internal use.

```ruby
require 'bundlebun'

# Path to the bundled Bun binary (platform-aware, includes .exe on Windows)
Bundlebun::Runner.binary_path
# => "/path/to/gems/bundlebun-0.5.0.1.2.5/lib/bundlebun/vendor/bun/bun"

# Does the binary exist?
Bundlebun::Runner.binary_path_exist?
# => true

# Relative binstub path (bin/bun or bin\bun.cmd on Windows)
Bundlebun::Runner.binstub_path
# => "bin/bun"

# Absolute binstub path
Bundlebun::Runner.full_binstub_path
# => "/app/bin/bun"

# Does the binstub exist in the project?
Bundlebun::Runner.binstub_exist?
# => true

# Preferred execution path: binstub if installed, raw binary otherwise
Bundlebun::Runner.binstub_or_binary_path
# => "/app/bin/bun"  (or the gem binary path if binstub not installed)

# Directory containing the Bun binary (useful for PATH manipulation)
Bundlebun::Runner.full_directory
# => "/path/to/gems/bundlebun-0.5.0.1.2.5/lib/bundlebun/vendor/bun"

# Direct instantiation (used internally)
runner = Bundlebun::Runner.new('--version')
runner.exec    # replaces process
runner.system  # => true / false / nil
```

--------------------------------

### Manually Enable ExecJS Integration

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

To manually enable bundlebun's Bun runtime support for ExecJS, call the `bun!` method on `Bundlebun::Integrations::ExecJS`.

```ruby
Bundlebun::Integrations::ExecJS.bun!
```

--------------------------------

### Bundlebun::Runner

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Provides low-level access to Bun execution and utility methods for locating bundled binaries and binstubs.

```APIDOC
## Bundlebun::Runner

### Description
`Bundlebun::Runner` is the underlying class for all Bun execution. It also exposes path helpers used by integrations and binstubs to locate the bundled binary and the installed binstub.

### Methods

#### `Bundlebun::Runner.binary_path`
- **Description**: Returns the absolute path to the bundled Bun binary. This path is platform-aware and includes `.exe` on Windows.
- **Returns**: String - The absolute path to the Bun binary.

#### `Bundlebun::Runner.binary_path_exist?`
- **Description**: Checks if the bundled Bun binary exists at the expected path.
- **Returns**: Boolean - `true` if the binary exists, `false` otherwise.

#### `Bundlebun::Runner.binstub_path`
- **Description**: Returns the relative path to the binstub (e.g., `bin/bun` or `bin\bun.cmd` on Windows).
- **Returns**: String - The relative path to the binstub.

#### `Bundlebun::Runner.full_binstub_path`
- **Description**: Returns the absolute path to the installed binstub in the project.
- **Returns**: String - The absolute path to the binstub.

#### `Bundlebun::Runner.binstub_exist?`
- **Description**: Checks if the binstub exists in the project.
- **Returns**: Boolean - `true` if the binstub exists, `false` otherwise.

#### `Bundlebun::Runner.binstub_or_binary_path`
- **Description**: Returns the preferred execution path: the binstub if installed, otherwise the raw bundled binary path.
- **Returns**: String - The path to use for executing Bun.

#### `Bundlebun::Runner.full_directory`
- **Description**: Returns the directory containing the Bun binary. Useful for `PATH` manipulation.
- **Returns**: String - The directory path of the Bun binary.

#### `Bundlebun::Runner.new(args)`
- **Description**: Direct instantiation of the runner (used internally). Creates a runner instance with the specified arguments.
- **Parameters**:
  - **args** (String or Array) - Required - Arguments to pass to the Bun executable.
- **Methods on instance**:
  - `exec`: Replaces the current process with Bun.
  - `system`: Runs Bun as a subprocess, returning control to Ruby.
```

--------------------------------

### Subscribe to Bundlebun Instrumentation Events

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

When ActiveSupport is available, bundlebun emits `system.bundlebun` and `exec.bundlebun` events. Subscribe to these events to log Bun command execution details.

```ruby
ActiveSupport::Notifications.subscribe('system.bundlebun') do |event|
  Rails.logger.info "Bun: #{event.payload[:command]} (#{event.duration.round(1)}ms)"
end
```

--------------------------------

### ExecJS Integration

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Manually enable the integration with ExecJS to ensure it uses the bundled Bun runtime.

```APIDOC
## ExecJS Integration

### Description
Manually enables the Bundlebun integration for ExecJS to utilize the bundled Bun runtime.

### Method
`Bundlebun::Integrations::ExecJS.bun!`

### Example
```ruby
Bundlebun::Integrations::ExecJS.bun!
```
```

--------------------------------

### Bundlebun Platform Detection

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Provides a helper to detect if the system is Windows, used for selecting correct binary names and extensions.

```ruby
require 'bundlebun'

# Check if running on Windows (mswin, mingw, or cygwin)
Bundlebun::Platform.windows?
# => false  (on macOS/Linux)
```

--------------------------------

### Relinking Bun with JavaScriptCore Changes

Source: https://github.com/yaroslav/bundlebun/blob/main/LICENSE.txt

Follow these steps to relink Bun with custom changes to JavaScriptCore. This process involves updating git submodules, compiling JavaScriptCore, and then building Bun.

```bash
git submodule update --init --recursive
make jsc
zig build
```

--------------------------------

### Bundlebun Framework Integrations

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Automatically patches framework libraries to use the bundled Bun. Integrations are auto-detected or can be activated manually.

```ruby
require 'bundlebun'

# Auto-load all detected integrations (called automatically on gem load)
Bundlebun::Integrations.bun!
# => [Bundlebun::Integrations::ViteRuby, Bundlebun::Integrations::ExecJS, ...]

# --- vite-ruby / vite-rails ---
# Patches ViteRuby::Runner#vite_executable to use bin/bun-vite
# Activated automatically if vite-ruby is loaded before bundlebun,
# or manually:
Bundlebun::Integrations::ViteRuby.bun!

# --- ExecJS ---
# Replaces ExecJS::Runtimes::Bun with a runtime pointing to the bundled binary
# and sets it as the default ExecJS runtime
Bundlebun::Integrations::ExecJS.bun!

# Verify ExecJS is now using bundled Bun
require 'execjs'
Bundlebun::Integrations::ExecJS.bun!
puts ExecJS.runtime.name  # => "Bun.sh"
ctx = ExecJS.compile('var double = function(n){ return n * 2; }')
puts ctx.call('double', 21)  # => 42

# --- cssbundling-rails ---
# Patches Cssbundling::Tasks to use bin/bun for install_command and build_command
# Activated via lib/tasks/bundlebun.rake (installed by rake bun:install:bundling-rails)
Bundlebun::Integrations::Cssbundling.bun!

# --- jsbundling-rails ---
# Patches Jsbundling::Tasks similarly
Bundlebun::Integrations::Jsbundling.bun!
```

--------------------------------

### Manually Enable Vite Ruby Integration

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

To manually enable the bundlebun integration with vite-ruby, call the `bun!` method on `Bundlebun::Integrations::ViteRuby`.

```ruby
Bundlebun::Integrations::ViteRuby.bun!
```

--------------------------------

### Bundlebun Instrumentation

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

When ActiveSupport is available, Bundlebun emits notification events that can be subscribed to for monitoring and logging.

```APIDOC
## Bundlebun Instrumentation

### Description
Subscribes to ActiveSupport notification events emitted by Bundlebun for monitoring.

### Events
- `system.bundlebun`: Emitted for `Bundlebun.system` calls.
- `exec.bundlebun`: Emitted for `Bundlebun.call` calls.

### Payload
- `command`: The Bun command arguments passed to the method.

### Example
```ruby
ActiveSupport::Notifications.subscribe('system.bundlebun') do |event|
  Rails.logger.info "Bun: #{event.payload[:command]} (#{event.duration.round(1)}ms)"
end
```
```

--------------------------------

### Vite Integration

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Manually enable the integration with vite-ruby/vite-rails to use the bundled Bun version.

```APIDOC
## Vite Integration

### Description
Manually enables the Bundlebun integration for vite-ruby and vite-rails.

### Method
`Bundlebun::Integrations::ViteRuby.bun!`

### Example
```ruby
Bundlebun::Integrations::ViteRuby.bun!
```
```

--------------------------------

### Uninstall Bundlebun Gem

Source: https://github.com/yaroslav/bundlebun/blob/main/README.md

Command to remove the bundlebun gem from your project. Follow up by manually cleaning up related files and configurations.

```sh
bundle remove bundlebun
```

--------------------------------

### Update PLATFORMS in Gemfile.lock

Source: https://github.com/yaroslav/bundlebun/wiki/Could-not-find-gems-matching-'bundlebun'-valid-for-all-resolution-platforms

Edit the `Gemfile.lock` file to specify the supported platforms. This is often necessary when targeting Linux and macOS.

```ruby
PLATFORMS
  aarch64-linux
  arm64-darwin
  x86_64-darwin
  x86_64-linux
```

--------------------------------

### ActiveSupport::Notifications Instrumentation

Source: https://context7.com/yaroslav/bundlebun/llms.txt

Emits notification events for subprocess and exec/call invocations when ActiveSupport is available. The payload includes the command arguments.

```ruby
require 'active_support/notifications'
require 'bundlebun'

# Subscribe to subprocess calls (Bundlebun.system)
ActiveSupport::Notifications.subscribe('system.bundlebun') do |event|
  Rails.logger.info "[Bun] #{event.payload[:command]} completed in #{event.duration.round(1)}ms"
end

# Subscribe to exec/replace-process calls (Bundlebun.call / .exec)
ActiveSupport::Notifications.subscribe('exec.bundlebun') do |event|
  Rails.logger.info "[Bun] exec: #{event.payload[:command]}"
end

# Both events include the raw arguments value
ActiveSupport::Notifications.subscribe('system.bundlebun') do |event|
  case event.payload[:command]
  when /install/ then Rails.logger.info "Bun: installed dependencies"
  when /build/   then Rails.logger.info "Bun: built assets"
  end
end

# Trigger an instrumented call
Bundlebun.system('install')
# => logs: "[Bun] install completed in 1823.4ms"
```
Tokens:
Raw