Node.js/CJS modules bundler
Bundle CommonJS/Node.js modules for web browsers.
- Require CSS and HTML files same way. Webmake allows you to require them too, which makes it a full stack modules bundler for a web browser.
Files support can be extended to any other format that compiles to one of .js, .json, .css or .html. See custom extensions for more information.
If you wonder how Webmake compares with other solutions, see comparison section
As it has been stated, Webmake completely follows Node.js in that
Let's say in package named foo you have following individual module files:
var sum = 0 i = 0 args = arguments l = argslength;while i < l sum += argsi++;return sum;;
var add = require'./add';return addval 1;;
var inc = require'./increment';var a = 1;inca; // 2
Let's pack program.js with all it's dependencies so it will work in browsers:
$ webmake program.js bundle.js
The generated file bundle.js now contains the following:
// about 60 lines of import/export path resolution logic"foo":var sum = 0 i = 0 args = arguments l = argslength;while i < l sum += argsi++;return sum;;var add = require'./add';return addval 1;;var inc = require'./increment';var a = 1;inca; // 2"foo/program";
When loaded in browser, program.js module is executed immediately.
Technically you can construct whole website that way:
Hello from NodeJS moduleSee Webmake for more details
documenttitle = "Hello from NodeJS module";require'./style';documentbodyinnerHTML = require'./body';var footer = documentbodyappendChilddocumentcreateElement'p';footerclassName = 'footer';footerinnerHTML = 'Generated by Webmake!';
$ webmake program.js bundle.js
See it working, by including it within document as such:
$ npm install -g webmake
$ webmake [options] <input> [<output>]
input - Path to the initial module that should be executed when script is loaded.
output - (optional) Filename at which browser ready bundle should be saved. If not provided generated bundle is streamed to stdout.
Name at which program should be exposed in your namespace. Technically just assigns exported module to global namespace.
Expose bundle as AMD module. If used together with name option, module will be defined with provided name.
Additional module(s) that should be included but due specific reasons are not picked by parser (can be set multiple times)
Additional extensions(s) that should be used for modules resolution from custom formats e.g. coffee-script or yaml.
See extensions section for more info.
Include source maps, for easier debugging. Source maps work very well in WebKit and Chrome's web inspector. Firefox's Firebug however has some [issues][firebug issue].
Ignore not parsable require paths (e.g.
require('./lang/' + lang)) or not polyfilled native modules requires (e.g.
require('fs')) if any.
Dynamic paths in require calls are considered a bad practice and won't be possible with upcoming ES6 modules standard. Still if we deal with modules that do that, we can workaround it by turning this option on, and including missing modules with
Enforce strict mode globally. Mind that by default in node.js environment CJS modules are not executed in strict mode. Relying on that feature may rise incompatibility issues in corner case scenarios.
Cache files content and its calculated dependencies. On repeated request only modified files are re-read and parsed.
Speeds up re-generation of Webmake bundle, useful when Webmake is bound to server process, see below example.
Highly recommended if extensions are used. Defaults to false.
Provide a transform middleware.
transform callback would be called on each module, with arguments: absolute filename and file code (as it is in origin file, before any internal transformations). If source module is meant to be processed by one of the extensions, you'll receive origin code before extension logic is applied, and you must return code that's valid for extension processor. So e.g. if you transform LESS code, you need to return valid LESS code
If you're interested only in applying transform to e.g. js files, be sure to filter your actions on basis of filename, and return code as you received if non transforms should be applied
In case of asynchronous operations, promise maybe returned, but it has to be promise that origins from deferred package.
webmakeprogramPath options callback;
webmake by default returns generated source to callback, but if output path is provided as one of the options, then source will be automatically saved to file
Currently best way is to use Webmake programmatically and setup a static-file server to generate bundle on each request. Webmake is fast, so it's acceptable approach even you bundle hundreds of modules at once.
You can setup simple static server as it's shown in following example script.
Example also uses node-static module to serve other static files (CSS, images etc.) if you don't need it, just adjust code up to your needs.
When you work with old school scripts or framework that uses different modules system, then you'd rather just bundle needed utilities (not whole application) and expose them to global scope.
Webassemble written by Ken Chen provides a convinient way to expose different packages, written CJS style, to outer scripts. It automatically creates one entry package that does the job and is used as a starting point for a Webmake bundle.
- YAML - webmake-yaml
Submit any missing extension via new issue form.
Install chosen extension:
EXT should be replaced by name of available extension of your choice.
$ npm install webmake-EXT
If you use global installation of Webmake, then extension also needs to be installed globally:
$ npm install -g webmake-EXT
When extension is installed, you need to ask Webmake to use it:
$ webmake --ext=EXT program.js bundle.js
Same way if used programmatically:
webmakeinputPath ext: 'EXT' cb;
Multiple extensions can be used together:
$ webmake --ext=EXT --ext=EXT2 program.js bundle.js
webmakeinputPath ext: 'EXT' 'EXT2' cb;
webmake-* NPM package (replace '*' with name of your extension), where main module is configured as in following example:
Extension doesn't need to be installed as package, you may pass it programmatically:
webmakeinputPath ext:name: 'coffee-script'extension: 'coffee'type: 'js'/* ... */cb;
See below writing extensions section to see how to configure fully working extensions
exportsextension = 'less';exportstype = 'css';return code: compileToCSSsource ; // `compileToCSS` returns plain CSS string;
Publish it and refer to Using extensions section for usage instructions.
Finally if everything works, please let me know, so I can update this document with link to your extension.
AMD is different format, and although most popular loader for AMD is named RequireJS it works very differently from require as introduced earlier with CommonJS (one that Webmake handles).
Main idea behind AMD is that dependencies are resolved asynchronously (in contrary to synchronous resolution in case of CommonJS format). Sounds promising, but does it really make things better? Cause of waterfall nature of resolution and large number of HTTP requests not necessary. See benchmark that compares resolution speed of both formats when used in development mode.
Agreed advantage of AMD that attributes to its success is that in it's direct form works in a browser (it doesn't require any server setup), that is hard to achieve with CJS style (but not impossible). Still due to large number of requests such approach is usually not suitable for production and it appears it's also not that performant in development mode.
Quirks of AMD style is that it requires you to wrap all your modules with function wrappers, its modules are not runnable in direct form in Node.js and dependency resolution rules are basic and limited if you compare it with design of node.js + npm ecosystem.
Browserify is most popular CJS bundler, and shares very similar idea. The subtle difference is that Browserify is about porting code as written for node.js to web browser, so apart of resolving dependencies and bundling the code it struggles to bring what is needed and possible from Node.js API to the browser.
Webmake cares only about bringing node.js modules format to other environments. Conceptually it's addition to ECMAScript and not port of node.js to browser. It makes node.js modules format runnable in any environment that speaks at least ECMAScript 3. You can bundle with Webmake for Browser, TV, Adobe Photoshop or maybe a modern dishwasher.
When comparing with other CJS bundlers, main difference would be that Webmake completely follows resolution logic as it works in node.js. It resolves both packages and modules exactly as node.js, and it doesn't introduce any different ways to do that. Thanks to that, you can be sure that your modules are runnable in it's direct form both on server and client-side.
Other important difference is that Webmake doesn't do full AST scan to parse require's out of modules, it relies on find-requires module, which does only what's necessary to resolve dependencies list, and that makes it a noticeably faster solution.
As soon as the standard will be finalized, implemented in first engines and possibly adapted by node.js Webmake will support it natively as well, then in a same way it will bundle it either for the sake of a bundle or for any ECMAScript 3+ environment that won't take it in natural way.
The application calculates dependencies via static analysis of source code
(with the help of the find-requires module). So in some edge cases
not all require calls can be found. You can workaround that with help
Only relative paths and outer packages paths are supported, following will work:
require'./module-in-same-folder';require'./module/path/deeper';require'./some/very/very/very/long' +'/module/path';require'../../module-path-up'; // unless it doesn't go out of package scoperequire'other-package';require'other-package/lib/some-module';
But this won't:
Different versions of same package will collide:
Let's say, package A uses version 0.2 of package C and package B uses version 0.3 of the same package. If both package A and B are required, package B will most likely end up buggy. This is because webmake will only bundle the version that was called first. So in this case package B will end up with version 0.2 instead of 0.3.
$ npm test
- @Phoscur (Justus Maier)
- Help with source map feature
- @jaap3 (Jaap Roes)
- Documentation quality improvements
[firebug issue]: http://code.google.com/p/fbug/issues/detail?id=2198 'Issue 2198: @sourceURL doesn't work in eval() in some cases'