Cajon is a JavaScript module loader for the browser that can load CommonJS/node and AMD modules. It is built on top of RequireJS.
You can use it to code modules for your project in CommonJS/node style, then use the RequireJS Optimizer to build all the modules into an AMD-compliant bundle. This allows you to then use a small AMD API shim, like almond, to get nicely optimized code without needing a full runtime loader.
Why use this instead of RequireJS? Some possible reasons:
- You cannot bring yourself to use a wrapper like this around your module code:
define(function(require) {
/*module code here */
});- You have a set of code already formatted in CommonJS/node style you want to reuse.
Otherwise, you should be using RequireJS, or another AMD loader.
Note the Restrictions section below. You will likely gnash your teeth in frustration if you do not heed them.
If you do not like this particular loader, but like the idea of a dual AMD and CommonJS/node style module loader, then you may like LinkedIn's Inject loader better.
Cajon is constructed with:
- RequireJS (needs 2.0.2 or later)
- An override to requirejs.load that fetches scripts via async
XHR requests then evals them, using the
//@ sourceURL=to specify the script names for script debuggers.
Cajon will only use the XHR+eval approach if the request is to the
same domain as the HTML document. If the script request is deemed to be on
another domain, it will just delegate to the default requirejs.load()
function, where it will load the script with a <script> tag, and expect it
to be in AMD format, or a traditional "browser globals" script.
You can override this behavior to use XHR for some cross domain requests if you know your users will be using CORS-enabled browsers and servers. See the Configuration section below.
Scripts that are fetched are wrapped in the following AMD wrapper:
define(function (require, exports, module) {
/* module code here */
});and it allows the use of __dirname and __filename inside that wrapped code.
Cajon assigns the cajon variable to the be same as the requirejs
variable, so you can use that if you want to specifically call out the usage
of cajon. However, the requirejs optimizer only understands
of require, requirejs and define, it will not understand cajon. This is
particularly important if you are using the optimizer's mainConfigFile
option.
It is best to just use the global require if you want the code to be
portable to RequireJS, almond and other AMD loaders, and only do detection
of cajon if you want to know if cajon is available.
There is a demo directory that shows example use, but basically,
put cajon.js in a <script> tag and load modules via require([]).
Note the Restrictions section below though.
To optimize the demo, run:
node tools/r.js -o demo/app.build.js
This will generate the optimized project in a demo-built directory. All
the modules in the build output will have been converted to AMD style, so
that they can be loaded cross-domain without needing special CORS
considerations.
The app.build.js build profile requires the r.js optimizer to be
version 2.0.2 or later, because it uses 2.0.2's cjsTranslate build option
that converts CommonJS/node modules to be define()-wrapped for the build.
If using volo:
volo add cajon
If using npm:
npm install cajon
Or URL to latest release:
https://raw.github.com/requirejs/cajon/latest/cajon.js
So do not expect to npm install some code, then be able to require it
using cajon.
Node uses multiple node_modules path lookups to find code and this is not
efficient to do in a browser context. Also, many node modules depend on
node's standard library or Node's environment, which are not available by
default in the web browser.
If you do want to use some npm-installed code, and you know it will run in the browser, you can get it to work with cajon, but you will likely need to use the paths, map and packages requirejs config to get it to work.
CommonJS/node module systems are synchronous, local file IO systems. So they allow these kinds of constructs:
//first example
var id = someCondition ? 'a' : 'b';
var a = require(id);
//second example
var a;
if (someCondition) {
a = require('a');
} else {
b = require('b');
}The first example will fail in an AMD browser environment, since all dependencies need to be known, downloaded and executed before the code runs. If 'a' and 'b' are not already in that state, that first example will likely generate an error.
The second example can work, but know that the AMD loader will download and execute 'a' and 'b' before running that code.
If you use a runtime decision to grab a dependency, use the callback-style require() supported by AMD loaders:
var id = someCondition ? 'a' : 'b';
require([id], function (mod) {
//do something with mod now
//that it has been asynchronously
//loaded and executed.
})Or consider creating an AMD loader plugin that can do the decision logic but still be treated as a single string literal dependency:
var dep = require('has!condition?succesModuleId:failModuleId');Both callback-style require and loader plugins are usable with cajon since it is just using requirejs behind the scenes.
Cajon will only use the XHR+eval approach if the request is to the same domain as the HTML document. You can override this behavior if you know CORS-enabled browsers and servers will be used.
Set up a useXhr function in a cajon config passed to the loader:
require.config({
cajon: {
useXhr: function (url, protocol, hostname, port) {
//Return true if XHR is usable, false if the
//script tag approach to an AMD module/browser globals
//script should be used.
//url is the url being requested.
//protocol, hostname and port area all values from the
//current page that is using cajon. Compare them with
//what is in `url` to make your decision.
}
}
});If you need to configure each XHR object before it sends out its request,
you can implement an onXhr method that gets called after xhr.open(), but
before xhr.onreadystatechange() is set up and before xhr.send() is called:
require.config({
cajon: {
onXhr: function (xhr, url) {
//xhr is the XHMLHttpRequest object.
//url is the URL the xhr object is set to use.
}
}
});MIT