How require() works

This wiki page is to talk about the require(<requirePath>) mechanism, to document how it works, and to give examples.

Say you have an application as follows:

apps/
| - testapp/
| - | - default-aspect/
| - | - | - index.html
| - | - | - src/testapp/App.js
| - | - | - src/testapp/subfolder/Util.js
| - | - libs/jquery/jQuery-2.0.0.js

If you wanted to include jQuery-2.0.0.js as a dependency you would write require('jquery');. The important thing to note here is that it's the directory name of the jquery library that is used as the parameter.

require() also supports relative paths. For example if 'App.js' wanted to pull in 'Util.js' you could write require('./subfolder/Util.js');. Or, alternatively, you could use an absolute require path instead, and write require('testapp/subfolder/Util.js');.

BRJS Libraries

apps/
| - testapp/
| - | - default-aspect/
| - | - | - index.html
| - | - | - src/App.js
| - | - libs/
| - | - | - myLibrary/MyClassA.js
| - | - | - myLibrary/subfolder/
| - | - | - myLibrary/subfolder/MyClassB.js
| - | - | - br.manifest

By default, the requirePath for 'MyClassA.js' would be require('myLibrary/MyClassA');, but this can be manipulated using the requirePrefix 'br.manifest' manifest attribute:

requirePrefix: myLibrary

We can edit the requirePrefix attribute to manipulate how we require the library and it's classes by changing the above property. For example, changing it to requirePrefix: myCompanyName/myLibrary, requires that the require path for MyClassA to become require('myCompanyName/myLibrary/MyClassA').

The important thing to note is that this has not lead to any file structure changes on disk.

Thirdparty Libraries

Thirdparty libraries have a 'library.manifest' file that allows you configure the dependencies of the library, and what the library exports when it's required, using the exports value

Assuming we have an application that looks like this:

apps/
| - testapp/
| - | - default-aspect/
| - | - | - index.html
| - | - | - src/testapp/App.js
| - | - | - src/testapp/subfolder/Util.js
| - | - libs/
| - | - | - jquery/
| - | - | - | - jQuery-2.0.0.js
| - | - | - | - library.manifest
| - | - | - jquery_plugin/
| - | - | - | - plugin.js
| - | - | - | - library.manifest
| - | - | - | - css/extraStyles.css

given that 'jquery_plugin' depends on 'jquery', the library.manifest file for 'jquery_plugin' would look like this:

depends: jquery
js: plugin.js
css: css/extraStyles.css
exports: jquery_plugin.object

Here's the complete list of manifest attributes:

• depends a comma delimited list of dependencies for the library, the order of which has no effect.
• js a comma delimited list JavaScript files to include within the source module for this library, included in the given order, where the paths are relative to the library root directory.
• css a comma delimited list CSS files to be bundled when this library is used, included in the given order, where the paths are relative to the library root directory.
• exports the JavaScript object that will be returned each time require() is invoked for this particular library.

Using the exports attribute from the earlier example, when someone requires the library via require('jquery_plugin'); the jquery_plugin.object object will be returned. At times, it may not make sense to return any specific object, in which case exports can be set to null.