automatic bundling of nodejs modules for the browser

  • script

Downloads in past


1900.1.410 years ago11 years agoMinified + gzip package size for script in KB


script Build Status
Use node.js modules in your client side scripts without thinking about it.
Dependency resolution and boilerplate is a job best left to a bundler and not a programmer. Script does all the heavy lifting to bundle your project files automatically with no additional build steps!
Script understands the simple commonjs require syntax to generate a single bundle or several bundles depending on your app caching requirements. This means you can use many node.js modules in the browser without any extra effort.
See the wiki for more details!

What makes script different?

small overhead no manual build steps leverage browser caching through external bundles shims for server only vs browser compat code
I hate having a build step and I also hate having to write boilerplate code just so my client side dependencies load right. One minor slip-up or misplaced script tag and nothing works! So I made script do the hard work for me.


At the core, script will bundle up your javascript files or npm modules for rendering as a unified javascript file which can be used with the script client require.js file.
To make a bundle from a script file or module
// create a bundle from a local file
var bundle = script.file('/path/to/local/file.js');

// create a bundle from a locally installed npm module
var bundle = script.module('cool-npm-moduel');

// rendering a bundle
bundle.generate(function(err, source) {
    // if no error, source will be a string with all of the dependencies rolled into it

connect/express middleware

Using the enchilada package you can easily serve your script processed js files.
See the enchilada docs for more information.


Some modules contain server specific code or dependencies. In order to allow such a module to be packaged, script supports the ``browser`` field in package.json.
The ``browser`` field allows modules to specify what files should be replaced with browser versions when packaging a module for browser use.
When you specify a single string for the ``browser` field, then that will replace `main`` and be the module entry point.
"browser": "./browser/specific/main.js"

If you specify an object, then you can replace modules or other files. This usage allows you to re-use much more of your javascript code.
"browser": {
    "module-a": "./shims/module-a.js",
    "./server/only.js": "./shims/server-only.js"

Now when you package your code, ``module-a` will be replaced with code from `./shims/module-a.js` and anytime `./server/only.js` is used, it will be replaced with `./shims/server-only.js``
If a module you depend on already includes a ``browser` field, then you don't have to do anything special. Whenever you require that module, it will automatically work. The `ws` and `xmlhttprequest`` modules are examples of this behavior.

advanced - external modules

While most users will be happy with the basic connect/express usage above, script is designed to fill complex app needs as well.
Most large scale apps use many javascript files. Some of these files are used on every page or act as "core" components. Instead of duplicating this code into every script bundle, script provides a way to create separate bundles for your core components. This allows you to better leverage browser caching between pages and further decreate the size of downloaded files.
An example (see examples/externals for the full source code):
Suppose you have a three files for your web app: core.js, pagea.js, pageb.js. core.js is required by all of your pages. When the user navigates from pagea to pageb, there is no need ot redownload the same core script.
var core = script.file('/path/to/core.js');

// we will setup a page_a bundle referencing the core bundle
var page_a = script.file('/path/to/page_a.js', {
    // specify that core is a dependency of page_a bundle
    externals: [
    main: true,
    client: true

// and similar for page_b
var page_b = script.file(...);

pagea.js nor pageb.js will not contain any code for core.js. Instead, they will make a request to fetch the code from the server (or from browser cache if applicable).
The only script your html page needs to have is the entry script (pagea or pageb) never core.js
<script src="/route/to/page_a.js"></script>

cli ##

Instead of adding boilerplate to your source files for "client side usage", just use the script command line tool to generate distributed versions of your library with all of the dependencies bundled.
bundle --name "my_module" /path/to/entry/point.js

Script will load the javascript file at the specified path and bundle all of the dependencies into a single file. The entry point module will be exposed to a variable with the given name (i.e. mymodule).
If you want to minify the output, just pass the ``--minify`` option and the output will be run through uglify-js.


Install with npm

npm install script