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:
- 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.
How does it work?
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:
and it allows the use of __dirname and __filename inside that wrapped code.
Cajon assigns the
cajon variable to the be same as the
variable, so you can use that if you want to specifically call out the usage
of cajon. However, the requirejs optimizer only understands
define, it will not understand
cajon. This is
particularly important if you are using the optimizer's
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
cajon if you want to know if cajon is available.
How to use it
There is a
demo directory that shows example use, but basically,
put cajon.js in a
<script> tag and load modules via
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
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:
Does not use node's module ID-to-path rules
So do not expect to
npm install some code, then be able to require it
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.
Avoid computed require('') calls.
CommonJS/node module systems are synchronous, local file IO systems. So they allow these kinds of constructs:
//first examplevar id = someCondition ? 'a' : 'b';var a = ;//second examplevar a;if someConditiona = ;elseb = ;
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';
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 = ;
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:
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: