Using CommonJS modules

CommonJS modules are a neat way to write JavaScript which doesn't pollute the global namespace. If you're used to using a server-side JavaScript platform (such as node.js) you'll be familiar with the advantages, and may even be able to re-use a few modules.

To add CommonJS modules to our app, we're going to use the modules package. This will load CommonJS modules from the filesystem and add them to our app.

Module format

Each module is evaluated in its own scope, and should not leak out variables that could affect other modules. To expose code from a module, you have to export it:

// say.js
exports.hello = function (name) {
    return 'Hello, ' + name + '!';
};

The exports object is automatically available when you're working inside a module. Any property added to this object will then be available to other modules which require this one.

Requiring modules

Inside a module you can require other modules by using the require function. This function is automatically available inside a module:

var say = require('say');

exports.alertHello = function (name) {
    alert(say.hello(name));  
};

Notice that we don't need to include the filename extension (.js) in the module path when requiring it.

For more details, check out the CommonJS modules 1.1.1 specification

Adding modules to your app

Let's create a file called lib/greet.js in the example app created in the Simplest possible app page:

// lib/greet.js
exports.sayHello = function (name) {
    alert('Hello, ' + name + '!');  
};

Then, update kanso.json with the modules package as a dependency:

{
    "name": "example-app",
    "version": "0.0.1",
    "description": "The simplest possible app",
    "attachments": ["index.html"],
    "modules": ["lib"],
    "dependencies": {
        "attachments": null,
        "modules": null
    }
}

We've also added a "modules" property set to ["lib"]. This tells the modules package which files and directories to search for modules. If any .js files are found they are added to the app.

Before pushing, we need to do kanso install again to get the new modules package:

kanso install
kanso push http://localhost:5984/example

If all went well, you should see:

OK: http://localhost:5984/example/_design/example-app/index.html

Great! We've added a module, now to do something with it.

Using modules in your app

By default, the modules package will generate an attachment (remember, this is just a static file served up by the app) called modules.js. This file will include the code for the require function, and all the modules you added to your app.

This behaviour can be turned off by setting "modules_attachment": "false" in your kanso.json file. But for now, we're going to leave it enabled and use the file in our index.html:

<h1>Hello, world!</h1>

<script type="text/javascript" src="modules.js"></script>
<script type="text/javascript">
    var greet = require('lib/greet');
    greet.sayHello('world');
</script>

Re-push the app:

kanso push http://localhost:5984/example

Now, when visiting the app's URL http://localhost:5984/example/_design/example-app/index.html, you should see an annoying "Hello, world!" popup!

Next

Get some JSON documents into CouchDB so we can start querying data: Adding example data.