Budo - Browserify Development Server

11.8.4 · abandoned · verified Tue Apr 21

Budo is a command-line interface (CLI) and programmatic tool designed for rapid prototyping with Browserify, providing a development server that focuses on incremental reloading and LiveReload integration. It serves a default `index.html`, bundles JavaScript with Browserify on the fly, and suspends HTTP responses until the bundle is ready, preventing stale content. A key feature is its ability to watch HTML and CSS files, injecting CSS changes without a full page reload, and providing clear error messages directly in the DOM and browser console. As of its latest stable release, 11.8.4 (published September 2017), the project appears to be in an abandoned state, with no significant updates in recent years. It differentiates itself by tightly integrating Browserify's bundling capabilities with a development server and LiveReload, offering features like SSL support and a rich API for custom development workflows, making it suitable for quick development cycles, especially for smaller client-side projects that leverage the Browserify ecosystem.

Common errors

```
Error: Cannot find module 'some-module'
```
cause A dependency required in your JavaScript file is not installed or Browserify cannot resolve it.

fix Run `npm install some-module` or `npm install --save some-module` in your project directory. Ensure `some-module` is correctly exposed if it's a non-standard path or global.
```
GET http://localhost:9966/bundle.js net::ERR_ABORTED 404 (Not Found)
```
cause The HTML file is requesting a JavaScript bundle at `bundle.js`, but Budo is either not configured to serve a bundle at that path, or no entry point was provided for bundling. This often happens if the HTML `script` tag references `bundle.js` but the `budo` command only provides `budo index.js`.

fix Ensure your `budo` command explicitly maps your entry file to `bundle.js`, e.g., `budo index.js:bundle.js`. If you're using `--dir`, make sure your HTML `script` tag's `src` attribute correctly matches the served bundle path.
```
(node:...) UnhandledPromiseRejectionWarning: Error: listen EADDRINUSE: address already in use :::9966
```
cause Another process is already using the default port `9966` (or the port you specified).

fix Stop the conflicting process or specify an alternative port for `budo` using the `--port` or `-p` flag, e.g., `budo index.js --port 8000`.
```
SyntaxError: Unexpected token import (or export)
```
cause Your JavaScript code uses ES modules (`import`/`export`) or other modern syntax not natively supported by the Browserify build without a transform like `babelify`.

fix Add a Browserify transform like `babelify` to your `budo` command: `budo index.js -- --transform [ babelify --presets=@babel/preset-env ]`. Ensure `babelify` and its Babel presets are installed (`npm install --save-dev babelify @babel/core @babel/preset-env`).

Warnings

breaking Major breaking changes in v5.0.0 include requiring `--` before any Browserify arguments (e.g., `budo index.js -- --transform babelify`), `--host` now defaulting to your internal IP (instead of localhost), and the removal of `--live-plugin`.
Fix: Adjust CLI commands to prefix Browserify arguments with `--`. Explicitly set `--host localhost` if you require local-only access. Migrate away from `--live-plugin` functionality.
breaking In v3.0.4, the `--outfile` and `-o` options were removed as Budo no longer performs file I/O for bundles. Additionally, `budo index.js` now directly serves `index.js` (or rather, the bundle for `index.js`), requiring adjustment if your HTML expects a `bundle.js` path.
Fix: Remove `--outfile` or `-o` from your `budo` commands. If your HTML refers to `bundle.js`, ensure your `budo` command maps the entry point to `bundle.js` using the `entry:outfile` syntax, e.g., `budo src/index.js:bundle.js`.
gotcha Any arguments intended for Browserify (e.g., `--transform`, `--plugin`) must be preceded by a `--` separator on the command line, otherwise Budo will interpret them as its own options.
Fix: Always use `budo entry.js -- --transform browserify-shim` to correctly pass arguments to Browserify.
gotcha LiveReload functionality for HTML, CSS, and JavaScript file changes is not enabled by default. CSS injection and full page reloads for HTML/JS require explicit activation.
Fix: Always include the `--live` flag in your `budo` command to enable LiveReload features. For specific file types beyond default JS/HTML/CSS, use `--wg` (e.g., `--wg **/*.{html,css,js,jsx}`).
gotcha By default, Budo serves files from the current working directory. To serve additional static assets (like `index.html`, `images`, `css` from a separate folder), you must specify a `--dir` option.
Fix: Use `budo --dir public/` to serve content from the `public` directory. You can specify multiple directories: `budo --dir public/ --dir assets/`.

Install

npm install budo npm
yarn add budo yarn
pnpm add budo pnpm

Imports

budo
wrong:
```
import budo from 'budo'
```
correct:
```
const budo = require('budo')
```
Budo is a CommonJS package primarily used via its CLI. The main export is a function that can be used programmatically to configure and start a development server.
serverEvents
```
const server = budo(entry, options); server.on('update', () => console.log('Bundle updated!'))
```
The `budo` function returns an EventEmitter instance (`server`) which can be used to listen for events like `'connect'`, `'update'`, or `'error'` for programmatic control.
budo CLI
```
budo index.js --live --open
```
The most common way to use `budo` is through its globally installed command-line interface, `budo`, which provides a robust set of options for serving, bundling, and LiveReloading.

Quickstart

This quickstart demonstrates how to use Budo's CLI to serve, bundle, and LiveReload a simple JavaScript application with Browserify and Babel, serving static assets from a separate directory.

// First, install budo globally:
// npm install -g budo

// Create an entry JavaScript file, e.g., `src/main.js`:
// console.log('Hello from Budo!');
// const element = document.createElement('h1');
// element.textContent = 'Welcome to your Budo app!';
// document.body.appendChild(element);

// Create a simple HTML file, e.g., `public/index.html`:
/*
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Budo Quickstart</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <script src="bundle.js"></script>
</body>
</html>
*/

// Create a simple CSS file, e.g., `public/style.css`:
// body { font-family: sans-serif; margin: 20px; background-color: #f0f0f0; }
// h1 { color: #333; }

// Run Budo from your terminal in the project root:
// budo src/main.js:bundle.js --dir public/ --live --open --host 0.0.0.0 --port 9988 -- -t [ babelify --presets=@babel/preset-env ]

// Explanation:
// - `src/main.js:bundle.js`: Bundles `src/main.js` and serves it as `bundle.js`.
// - `--dir public/`: Serves static files from the `public/` directory.
// - `--live`: Enables LiveReload for HTML, CSS, and JS changes (CSS injected, HTML/JS reloaded).
// - `--open`: Automatically opens the server URL in your default browser.
// - `--host 0.0.0.0 --port 9988`: Makes the server accessible on all network interfaces on port 9988.
// - `-- -t [ babelify --presets=@babel/preset-env ]`: Passes a transform to Browserify (e.g., Babelify for modern JS syntax).
//   (Requires `npm install --save-dev babelify @babel/core @babel/preset-env`)

view raw JSON →