Brief

JS-Class-Loader reads a codebase of javascript class files and generates a single module file of code. It uses name and folder conventions to detect dependencies and automatically put the code into the correct order.

It is written in Java (and is simple to integrate with Java web apps) but is also useful with static web sites (you can use it in your IDE), other scripting languages or any build tool.

Less brief

Developers working on large javascript codebases will know that if you are writing serious amounts of javascript your codebase can very quickly get messy and become hard to manage. Things that work for a rapid prototype often turn into a mess when the codebase grows. This tool imposes code conventions that keep your code neat, clean and easy to manage no matter how large it gets. It uses these conventions to detect dependencies and bundle your code for you, so that you can add, remove and refactor code and files without having to do anything to your script tags. It is fast enough even on large codebases that it allows you to make a change, reload the browser and see the change.

If your project is a java webapp already then this tool will integrate seamlessly as either a runtime servlet or a build time task. If your project is any other sort of application then you can use JS-Class-Loader from your IDE or your build to manage your javascript code quickly and simply.

Principles

JS-Class-Loader was designed with the following requirements in mind:

• Must allow the developer to make a change, reload the browser and see the change in a way that does not take any significant time
  even on very large codebases (target: ~3,000 source files, 3MB of source)
• Must allow the developer to debug at the correct source line
  currently this means development mode has individual script tags, in future this may be implemented with source maps and/or just breaking out individual modules into script tags.
• It must work seamlessly from the IDE without requiring any non-java tools or software
  e.g: must not require the developer to run V8, NodeJS and Grunt just to bundle the js code. This reduces the number of moving parts and points of failure, and allows new developers to get up and developing on your project quicker.
• Must integrate with existing project structures
  For anything other that the simplest use (bundle all files), JS-Class-Loader does impose structure rules on code in order to do dependency detection. It requires the concepts of namespaces and names, and for code to be referenced that way when it is used, but it will always be completely configurable about where and how many source trees there are, how you define your names, and if you use inheritance then it must be possible to configure JS-Class-Loader to recognize it and use it for dependency management.
• Must be well documented, have good defaults and excellent error messages
  The developer should be able to run the jar and muddle their way along to successfully setting up their project purely by reading the help and error messages and then setting the settings. The docs must cover all basic setup procedures and provide examples and tutorials, and these must be kept up to date. It must NEVER fail silently or provide blank or misleading error messages.

Rules of JS-Class-Loader

1. Class names must match file names
   Whether it's a class, a static object, a function or anything else, the thing in the file must match the name of the file. This is so that when you reference the thing, JS-Class-Loader knows to include the file.
2. Folder structure must match package structure
   This is the tried and tested code convention that Java uses, and allows you to separate your code into modules and groupings. You can still have that big messy util file in the root namespace if you want but JS-Class-Loader allows and encourages you to use proper code structure in your javascript.
3. File names must not have extra dots in them
   JS-Class-Loader uses dots for namespaces and gets confused when a filename has dots in it. This may be fixed in future (by converting them to underscores) but for now, no dots in filenames apart from the .js extension. (dashes and underscores in filenames are ok though, we recommend converting dots to underscores)

Having said that, you can still include files, 3rd party libraries and modules in your bundle that don't conform to this scheme. You just need to explicitly include them in your code somewhere, you can't just rely on dependency detection to work out that you need them. There are plenty of examples in this site of how to include the most common js frameworks and libraries in your codebase