jsbundle

jsbundle -- Node.JS modules for the browser

jsbundle takes your Node modules and makes them work in the browser.

It finds all require calls in your code and includes the necessary module files. Then, it wraps all these modules using the Node variant of CommonJS module headers.

It handles node_modules directories and package.json files just like Node does.

It comes with a "Dev CDN" that will watch your files for changes and serve the latest jsbundled version of your code via local HTTP.

It has good error handling and runs without any configuration.

Usage

jsbundle

[JSBUNDLE_ENV=<env>] jsbundle <entry_file> [--config=config_file] [--env=env]

Bundle up entry_file and all its dependencies, optionally using configuration specified in config_file, and write it to stdout. If no config_file is specified, jsbundle will look for a jsbundle.json file in the current working directory and use that if it exists. You can specify the JSBUNDLE_ENV either via an environment variable or by passing a value to the --env flag.

This command is basically equivalent to running:

node <entry_file>

in the sense that when the resulting script is executed in the browser, the module entry_file will be the first module to begin executing.

For production deployment, you'll probably want to pipe the resulting output to the JavaScript minifier of your choice.

devcdn

[JSBUNDLE_ENV=<env>] devcdn [config_file] [--port=tcp_port] [--env=env]

Start a "Dev CDN", serving on tcp_port (default 8081), optionally using configuration specified in config_file. The entry_file passed to jsbundle is determined by the request URL, which will be resolved based on the devCdnPaths defined in the config file (defaulting to the current working directory of devcdn). If no config_file is specified, devcdn will look for a jsbundle.json file in the current working directory and use that if it exists. You can specify the JSBUNDLE_ENV either via an environment variable or by passing a value to the --env flag.

Tests

Test coverage is currently mediocre. You can run tests with:

npm test

Caveats

• All values passed to require in your code must be string literals. Otherwise, jsbundle wouldn't be able to reliably find all the modules to include in the bundled output.

• The special variable __filename is equal to the module.id. If you specify the mangleNames option (see below), then the __filename will be the mangled numeric id of the module.

• The special variable __dirname doesn't really make sense in the context of browser modules, so while the variable exists, its value is undefined.

Configuration and JSBUNDLE_ENV

{
  "defaults": {
    "filters": [
      "logger"
    ],
    "loggerLevel": "debug"
  },

  "production": {
    "loggerLevel": "error"
  }
}

jsbundle uses the "defaults" configuration as a base, and then, depending on the value of the JSBUNDLE_ENV environment variable, overrides or adds more values. In the example above, if the value of JSBUNDLE_ENV is "production", "loggerLevel" will be "error" instead of "debug".

See the included jsbundle.json for an annotated example of all configuration options.

Thanks To

• substack for his browserify package, which served as inspiration for jsbundle.