mundle

A client-side module loader with server-side bundler and cacher

npm install mundle
11 downloads in the last week
44 downloads in the last month

Mundlejs

Build Status

Module bundler, cacher, and client-side loader
Demonstration:

Mundlejs is the next generation client-side package manager. It does all the things we've come to expect a decent package manager to do and more. For example:

  • Unobtrusive and compatible- All you have to do to define a package is define its exports, using module.exports, just like you're know and love from node.js. Real reuse of js between node and the client. All those little helpers and utilities now only need to exist in one place in your codebase and there are no special build steps to convert between them.
  • Simple but powerful syntax for client-side script loading- Based on the syntax of your require statements it is very natural to define which dependencies will be required immediately and which can be loaded asynchronously. This means you can keep your client-side code as modular as you've been keeping your server-side code and as it should be. At the same time, there's no build step or concatenation of scripts; rather, mundle smartly loads exactly the dependencies your application needs in one, optimized request.
  • Share packages in a centralized repository- Using the bower api, mundle has built-in package support. That means using a new library or module is as simple as one "mundle install package" and one "var packageFunction = require('package')"
  • Super fast-
    • Only the code you actually need is served in each request, not your entire codebase. You define small, smart dependencies. Then you define which dependencies are necessary immediately and which can be deferred and fetched asynchronously. But you don't have to think about it- the syntax is very natural. Then mundle takes care of packaging into exactly optimized packages.
    • Mundle uses cacheing all over the place to be able to serve requests fast, fast, fast. See the blog posts below for testing results.
    • Coming soon- cdn plugins that will serve your cached bundles from cdn.
  • Parseing plugins- Mundle supports plugins for compiling source files- so using coffee, jade-templates, etc. is a breeze

Installation

npm install mundle

Basic Usage

Server-side

    serverRequire = require('mundle');
    serverRequire.setBasePath('pathToMakeIntoTheClient-sideRoot');
    serverRequire.listen(3000);

Server-side using Connect(/Express)

    connect = require('connect');
    mundle = require('mundle');
    app = connect()
        .use(mundle.connect('pathToMakeIntoTheClient-sideRoot')
        .listen(3000);

Client-side

    <script type='text/javascript' src='mundlejs/require.js'></script>
    <script type='text/javascript'>
            require('somePath',function(error,exportsFromSomePath){
                    console.log('Yayyy!');
            };
    </script>
  • somePath can be
    • 'moduleName[@version]' resolves to server-side basePath/mundles/moduleName/(version|default)
    • './some/relative/path/to/file.js' resolves to server-side basePath/some/relative/path/to/file.js
  • in this form, somePath will be loaded asynchronously as the syntax suggests

Inside a file, you can require use an asynchronous syntax (and delay loading that bundle until the require is executed) or using a synchronous syntax:

    someModule = require('somePath')
  • somePath is resolved as before
  • in this form, somePath is bundled with the file containing this require and returned in the same request as a dependency. When this line executes, the code is already available and just needs to be executed.

What do modules look like:

  • one module per file
  • the syntax for exports should look familiar :) :

      module.exports = whateverYouWant
    
  • Yes, that is all.

Installing mundles

    mundle install package

uses bower, so all bower packages are available here: http://sindresorhus.com/bower-components/

Defining mundles

Uses package.json with name, version, and main fields. main defaults to 'index.js' mundles are bower packages, so follow their instruction to use the centralized repo and the package dependency resolution: https://github.com/bower/bower

Plugins

    plugin = require(plugin);
    mundle.use(plugin);

or

    plugin1 = require(plugin1);
    plugin2 = require(plugin2);
    mundle.use([plugin1, plugin2]);
  • plugins allow you to pre-compile files before mundle attempts to parse them
    • e.g. Jade template files, for including pre-compiled client-side, or coffee
  • plugins look like:
      {extensions: [an array of file extensions, e.g. 'coffee', 'jade']}
    
  • check my other repos for jade and coffeescript plugins

Tests

  • To run automated tests
      cake test
    
  • To run manual tests
      cd tests/manual     
      node server.js
    

Contribute

  • Suggestions of how to make this more useful/robust/pluginable/available to more people very welcome
  • Improve compatibility with Commonjs module specification
  • Performance
  • Bug reports
  • Pull requests
  • Can this be generalized, for example automatic optimization of spriting from css files?
  • Plugins for processing files? e.g. compile jade templates
  • Check out the issues for ideas on what you can implement

Coming soon

  • https (might already be working ;) untested)
  • more tests (especially client-side)
  • cacheing
    • client-side
    • cdn
      • have some ideas about cacheing to cdn's for really great performance
  • check out the issues for more

Blog posts

Copyright (C) 2013 Saleem Abdul Hamid
Licensed under the MIT license

npm loves you