Working with modules and libraries in Tabris.js

January 23, 2015 | 3 min Read

Tabris.js implements a module system as outlined by Common.js and supported by npm. Modules are a great way to organize your application code into isolated units. Unlike conventional scripts they keep the global namespace clean and are automatically loaded in the right order.

Script modules

The most common way to create a module is to use a single JavaScript file. There are some important differences to conventional scripts (e.g. as used in HTML documents):

Script modules have an implicit scope, i.e. using var will never create a global variable.
Each module has a unique, implicitly created local module object to export data.

The script, let’s say “mymodule.js”, may attach data to the module.exports object, which is also available under the shorter alias exports:

exports.foo = 1;
exports.bar = 2;

This data can then be imported from another script in your project, e.g.:

var data = require("./mymodule");
console.log(data.foo);

All modules are cached, so the code needs to be loaded only once, and there is always exactly one global instance of its exports. The exported data may consist of anything a JavaScript object can contain, e.g. primitive types, arrays, or functions.

JSON modules

The simple mymodule example above could also be implemented as mymodule.json:

{
  "foo": 1,
  "bar": 2
}

This is a very convenient way to store and load completely static data, for example language-specific strings for internationalization. Obviously it doesn’t work when exporting any type of data created dynamically or not supported by JSON, e.g. functions.

Package modules

A more complex module may consist of multiple files, e.g. sub-modules, images and documentation. In that case the name of the module is the name of the folder. To determine which file from the folder to load first, a package.json file with a “main” entry should be present in the folder. It typically looks something like this:

{
  "name": "mega-module",
  "version": "1.0",
  "author": {
    "name": "Guy Incognito",
    "email": "[email protected]"
  },
  "main": "my-main-script.js"
}

Organize your project any way you like

Modules can be placed anywhere in your project. They are identified by a path relative to the script that calls “require”, so as your project grows other imports may look like this:

var names = require("./names");
var verbs = require("./en/verbs");
var stringUtil = require("../common/stringUtil");

A file extension may be given, but is optional. Omitting it allows you to later change the nature of the module (.js, .json or package).

Working with npm

The npm command line interface lets you, once installed, download modules uploaded by other developers into your project folder. E.g. to install Underscore.js, simply type in your project folder:

$ npm install underscore

When you are importing npm modules, they are identified simply by their name, not their path:

var _ = require("underscore");

A list of dependencies to npm modules is stored in your project’s package.json. Therefore you don’t need to upload these modules to your repository, they can be installed all at once simply be typing “npm install”.

The npm database hosts JavaScript modules for various JavaScript runtime environments, so not everything there is compatible with Tabris.js. But anything that depends solely on EcmaScript API will definitely work, and modules for web applications may also work if they do not use HTML.