View on GitHub


(Java) Fast Javascript aggregator / bundler. With dependency detection.

The javascript weapon of a more civilized age.
Download the latest release jar file Download this project as a tar.gz file

Fast overview

A Java program to bundle together your javascript and generate source maps by inspecting the code for dependencies.

Some javascript codebases use a Java style class structure, where each class is in a file with the same name as the class inside it, and each class namespace matches the folder tree that it is in. A project may have many modules and source roots but inside each one the code is organised in a java style class/package structure.

If your project structures it's code in this way, then this bundler will automatically detect dependencies and include them. And if you use the standard extends() function for class inheritance, then this bundler will automatically know to generate the dependency list in the right order.

E.g: imagine ypur source roots are script/ and modules/* (so that each folder in modules is a source root)
script/app/Main.js contains the class app.Main
modules/audio/lib/audio/Sampler.js contains the class
modules/services/lib/rest/DataService.js contains the class

If app.Main uses the class audio.lib.Sampler then the bundler will see that and know to include the Sampler class. You don't need to specify it or manually list your classes dependencies. If some of your code doesn't conform to the standard structure then you can manually include it with the include function.

It is written in Java and works as either a command line tool (which can run as a watcher while you code) a builder inside your IDE, a server side generator in Java apps, and as a step in your build.

How to run it -

Try it out on the command line

You need to have Java 1.7 or higher installed. Then find a seed class, source folder and output file, and run the bundler like this:

java -jar js-class-loader-1.2.18.jar --sourcePaths=src --bundleFile=gen/bundle.js

Check your output file to see what's in there.

Move your config into a config file

Once you've got the basic bundling going on the command line, put your config options into a file, and put it it wherever you keep your config files. Add the basePath option into your config file to make sure it always runs from the right place.

You can then run the bundler again with

java -jar js-class-loader-1.2.18.jar --config=conf/

Run it as a file watcher

Sometimes an out-of-IDE process to bundle your code is the most effective way. To run JSCL like this, add --watchFiles=true on the command line

java -jar js-class-loader-1.2.18.jar --config=conf/ --watchFiles=true

Run it from your IDE

In eclipse you can set up a project builder that runs the jar and specifies the arguments. Use the same arguments as you would from the command line.

Add it to your Maven build

Add the following dependency to your pom.xml dependencies section:


And add the following plugin to your build/plugins in your pom.xml file:


What is the point of all of this?

Mainly this tool is for javascript developers working in a java web app environment that want to manage a large js codebase with a neat, convention based code structure without having to worry about manually managing dependencies or installing a suite of other compilers, runtimes and tools to bundle their javascript up.

No java knowledge is required to run the bundler though, so any developer could use it if they felt inclined.


Maven integration in eclipse is hard and bad, not just with JSCL but with Eclipse M2E and maven in general. Maven may change files and metadata outside of the project, making it difficult for M2E to guarantee that it's build does the same thing as the maven build. The issue is covered in great detail here, in the M2E wiki on "Plugin execution not covered"

So the eclipse approach to custom maven plugins is to either force you to add m2e specific config to your project files, which is bad, or write a specific M2E configurator which is bad too, and lots of pointless work to keep it working, tested and up to date. Having said all of that, it is possible to use the maven mojo effectively from within eclipse, it's just that like with most things eclipse and maven, you might find yourself having to know rather more about maven than you'd like, if you want to fix any random spurious error messages you get when your project gets messed up. Generally I prefer to use the bundler as a builder from eclipse and only use the mojo at build time, being confident that the bundles will end up identical. However some developers might get a bit uncomfortable with a bundle file being generated in a different way in dev to in the deployed build.

How fast (or slow) is it?

The command line execution process is basically the time it takes for the jvm to start, the files to be read and then a very small amount of time to generate the dependency tree and write out the bundle. For projects of under 100 files the command line runner will complete in under a second, for a thousand source files it will run in a few seconds. If it is run in file watcher mode then it will be much, much faster again.