There is an ongoing debate about client-side javascript modularisation and yet – until the harmony modules are here and probably not even then – there isn’t an agreement on what should be the best solution. We at WAVE have decided to go for the CommonJS format to package our libs – which is one of the projects that aims to standardise modules and packages in javascript, in their own words
“CommonJS is a project with the goal of specifying an ecosystem for JavaScript outside the browser”.
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 wako since 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.
Next to index.js and 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 <module-name>.min.js.
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).
We also ship a Gruntfile with the whole lib that contains means to compile your own version of the lib, and launch the test suite. Why grunt? it seems to be nowadays the most widespread task runner in the javascript community, although there are some new kids on the block.
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 grunt test.