How-To: Create a JavaScript module for CommonJS, Ti.include, or the browser

Fresk leaves invoking a happy mood.

A common question we get is around techniques for code re-use between projects that use different types of JavaScript evaluation mechanisms, like the CommonJS module spec, Ti.include, or just in the browser. I thought I’d share a quick technique for creating a JavaScript module that will work in all three of these environments. Here’s the template for a simple module, before we dive into the usage:

In a CommonJS environment, we’ll add our public interface to the exports object as usual. But in environments that don’t provide the export object and an automatic sandbox, we need to be conscious of polluting the global JavaScript object by adding lots of global properties and functions. We can achieve this using a self-calling function to encapsulate the logic of our module, and only expose a single variable to the global scope, which we called globalNamspace above. This variable will become the public interface to our module in a Ti.include-style usage or in a standard script tag in the browser. To use the module in a CommonJS environment, your usage would look like this:

Using Ti.include, it would look like:

And in the browser, it would look like:

I hope that helps you create JavaScript modules that can be re-used in any environment.


  1. Very interesting, Kevin. Very useful for future implementation of html5 with titanium. But I can’t figure out a scenario where the same module would be loaded with include and require, and this should introduce additional cautions that where not necessary working with “pure” commonJS modules or “pure” includes.

    For example, declare globalSpace at the header of the file can be a bit dangerous if we have more than one include. Would be better to check if globalSpace already exists before declare it again in all includes. And this practice would do a bit less reusable a file, since that globalSpace var could change from one app to another.

    Any way, good entry, thanks for share

  2. To clarify, in Titanium you would not use BOTH require and Ti.include if you could avoid it, if only for the sake of uniformity.

    You’re right, in the browser/Ti.include scenario, you might be overwriting a variable in the global scope. This is a fundamental problem with JavaScript. You could check to see if it was already defined, and essentially add functions to the object if you felt that was appropriate. But to create a module, you need to have at least one global variable (namespace).

    To paraphrase a popular JavaScript proverb: the global scope is like a public restroom – sometimes you’ve got to go in there, but when you do, try and limit your contact with surfaces. 🙂

  3. Hi Kevin,

    How does this method effect modules built with dependencies on other modules using “require” for example?

    • It wouldn’t per se – this technique is intended to be used to build your own modules, which could be reused in the browser or commonjs environments

  4. Is there any other advantage to using CommonJS over Ti.include other than the ability to reuse in CommonJS environments.

    • @Mat the big one is security. You can explicitly control your module’s public interface without the self-calling function boilerplate. Consumers can also namespace modules wherever it makes sense for them, instead of relying on the module developer to put their code in the right place in the global scope.

Comments are closed.