Clone wiki

jsbundle / Home


It's best to describe what jsBundle does by example. Take a directory of javascript files:


In that, we put:

import jsbundle
jsbundle.make( 'project', scan='js' )

This tells jsbundle to make a bundle named 'project' scanning the 'js' directory for javascript files. make() can take a bunch of options, which are described below, or you can gain even more control using the Builder class.

When we run "python". It creates a build directory in project:

    js/ ...


The only argument required is a name.

Here are the keyword arguments:

A list of requirements to build. This allows you to build only the modules you want, and any modules that are required by them. This defaults to None, meaning build all the modules found.

A path string or iterable of path strings to scan for files. This defaults to 'js'.

A regular expression that must be matched for the source to be included as a module. It must contain a named group "name", that will define the name of the module. It defaults to ^(?!test_|__)(?P<name>.*)\.js$

Like *src_match* above, but to gather test files. It must also define a named group "name". It defaults to ^test_(?P<name>.*)\.js$.

In the following string arguments, one can include these variables to be expanded: "%(name)s", which is the first argument, "%(hash)s" which is the first 8 characters of the hash of the full bundle, and finally "%(fullhash)s", which is the full hash of the bundle.

Also, they define paths to create files at, all directories needed to get to that end point will be created if need be.

A path string to the main build file. This is the combined full source of all the modules to be bundled.
defaults to: build/%(name)s-%(hash)s.js

A path string to the minified build file. This is the combined source of all modules after being minified, meaning all comments are stripped, and useless whitespace removed.
defaults to: build/%(name)s-%(hash)s.min.js

A path string to the test file. All test files found that can be matched up to modules will be combined into this one file.
defaults to: build/%(name)s-%(hash)s.tests.js

A path string to a json document of documentation entries. Read the documentation section for more information on entries.
defaults to: build/%(name)s-%(hash)


The best way to read about the Builder class is to see it being used with in the of jsbundle, or by reading the class itself in


When compiling the documentation, jsbundle will gather all documentation entries in the source files it scans. Entries are defined by any comment that begins with two stars /** and ends with two stars **/. The first line of an entry should be its name, or a blank line. The second line will define the indentation to keep, so every proceeding line must match the indentation defined by the second line. Finally, if an entry line starts with '@requires', the rest will be split on whitespace, and used as requirements.

Let's define an entry in 'core.js':

/** Project.core
 Our core functionality.

Here we define an entry named "Project.core", with the content. Now we'll reference "Project.core", in 'util.js':

/** Project.util.ajax 
 * @requires Project.core
 * Various ajax utility functions.

Here we proclaim "Project.util.ajax". We say it requires "Project.core", which is an entry we've already defined. This will ensure that 'core.js' is included whenever 'util.js' is. We could also say '@requires core', where 'core' is the name of the module 'core.js'.

Finally, if we want to define help content only for the module, and not necessarily a named entry, we can leave off the name:

  * This module is a collection of fun-loving constants.

This actually creates an entry with the name of the module.