automatic bundling of nodejs modules for the browser
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!
- 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.
To make a bundle from a script file or module
// create a bundle from a local filevar bundle = scriptfile'/path/to/local/file.js';// create a bundle from a locally installed npm modulevar bundle = scriptmodule'cool-npm-moduel';// rendering a bundlebundlegenerate// if no error, source will be a string with all of the dependencies rolled into itconsole.logsource;;
Using the enchilada package you can easily serve your script processed js files.
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.
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":"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
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
xmlhttprequest modules are examples of this behavior.
While most users will be happy with the basic connect/express usage above, script is designed to fill complex app needs as well.
An example (see examples/externals for the full source code):
Suppose you have a three files for your web app: core.js, page_a.js, page_b.js. core.js is required by all of your pages. When the user navigates from page_a to page_b, there is no need ot redownload the same core script.
var core = scriptfile'/path/to/core.js';// we will setup a page_a bundle referencing the core bundlevar page_a = scriptfile'/path/to/page_a.js'// specify that core is a dependency of page_a bundleexternals:coremain: trueclient: true;// and similar for page_bvar page_b = scriptfile;
page_a.js nor page_b.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 (page_a or page_b) never core.js
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
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