CommonJS is implemented in the popular server platform nodejs, and has been so successful that several adapter libraries have been created in order to use it in the browser as well. It will allows us to properly manage our inter-dependencies while opening the doors to the extensive module collection from the node community through npm.
Another requirement we had for our libs was the possibility to export modules separately as well as a compact lib, becoming an umbrella namespace for visual and audio libs altogether, something quite trivial to do once the CommonJS system is in place. The whole exported package will be then
wave.js already exsists elsewhere .
There are different ways CommonJS modules can be consumed client-side like browserify, requirejs or jspm among others. For a more detailed reflexion on the topic I find this post to be quite complete.
Once that out of the way, here is what our modules will typically look like:
1 2 3 4 5 6 7 8 9 10 11 12
The aim of our setup is to make sure the library contains the essential parts to be included right away in your project.
The proposed structure probably looks familiar to you if you know
node modules, as it’s the de-facto structure of an
npm module. The strictly necessary files for a module here are
index.js – the module file – and
package.json which contains relevant information about our module, such as name, the current version, dependencies, authors etc. There are plenty of documentation on this, so I won’t go into details in this post, you can find a list of resources at the bottom.
package.json, we want to make sure the user will have ready-to-use browser compatible versions of our lib
<module-name>.js, and it’s loyal minified companion
Then follows the README file with the relevant instructions and a LICENCE file (in our case of type BSD-3 for most of the packages).
Documentation can be generated via
grunt jsdoc, this will generate a doc directory in the root of your module containing the docs in html format.
As for the tests, there is a
testrunner.html in the tests directory that will run all the specs for you. When there is no browser code involved you can also run the tests via