forked from requirejs/requirejs
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathnode.html
More file actions
131 lines (92 loc) · 7.19 KB
/
node.html
File metadata and controls
131 lines (92 loc) · 7.19 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<div id="directory" class="section">
<h1>RequireJS in Node</h1>
<ul class="index mono">
<li class="hbox">
<a href="#1">Doesn't Node already have a module loader?</a><span class="spacer boxFlex"></span><span class="sect">§ 1</span>
</li>
<li class="hbox">
<a href="#2">Can I use server modules written in the CommonJS module format?</a><span class="spacer boxFlex"></span><span class="sect">§ 2</span>
</li>
<li class="hbox">
<a href="#3">How do I use it?</a><span class="spacer boxFlex"></span><span class="sect">§ 3</span>
</li>
</ul>
</div>
<div class="section">
<h2>
<a name="1">Doesn't Node already have a module loader?</a>
<span class="sectionMark">§ 1</span>
</h2>
<p>Yes <a href="http://nodejs.org">Node</a> does. That loader uses the CommonJS module format. The CommonJS module format is <a href="why.html">non-optimal for the browser</a>, and I do not agree with <a href="http://tagneto.blogspot.com/2010/03/commonjs-module-trade-offs.html">some of the trade-offs made in the CommonJS module format</a>. By using RequireJS on the server, you can use one format for all your modules, whether they are running server side or in the browser. That way you can preserve the speed benefits and easy debugging you get with RequireJS in the browser, and not have to worry about extra translation costs for moving between two formats.</p>
<p>The situation has improved a bit in Node 0.5.0 and later, which supports the <a href="commonjs.html#manualconversion">"simplified CommonJS wrapper" version of define()</a>. While this is helpful for some base library purposes, it does not include support for <a href="api.html#defdep">dependency arrays in define()</a> or <a href="plugins.html">loader plugins</a>. So using the r.js RequireJS adapter is useful for making sure your code will run as you expect across browser and Node environments.</p>
</div>
<div class="section">
<h2>
<a name="2">Can I use Node modules already written in the CommonJS module format?</a>
<span class="sectionMark">§ 2</span></h2>
<p>Yes! The Node adapter for RequireJS, called r.js, will use Node's implementation of require and Node's search paths if the module is not found with the configuration used by RequireJS, so you can continue to use your existing Node-based modules without having to do changes to them.</p>
<p>RequireJS will use its <a href="api.html#config">Configuration Options</a> first to find modules. If RequireJS cannot find the module with its configuration, it is assumed to be a module that uses Node's type of modules and configuration. So, only configure module locations with RequireJS if they use the RequireJS API. For modules that expect Node's APIs and configuration/paths, just install them with a Node package manager, like <a href="http://npmjs.org/">npm</a>, and do not configure their locations with RequireJS.</p>
<p><strong>Best practice</strong>: Use npm to install Node-only packages/modules into the projects <strong>node_modules</strong> directory, but do not configure RequireJS to look inside the node_modules directory. Also avoid using relative module IDs to reference modules that are Node-only modules. So, <strong>do not</strong> do something like <strong>require("./node_modules/foo/foo")</strong>.</p>
<p>Even though RequireJS is an asynchronous loader in the browser, the RequireJS Node adapter loads modules synchronously in the Node environment to match the default loading behavior in Node.</p>
<p>Finally, RequireJS in Node can only load modules that are on the local disk -- fetching modules across http, for instance, is not supported at this time.</p>
</div>
<div class="section">
<h2>
<a name="3">How do I use it?</a>
<span class="sectionMark">§ 3</span>
</h2>
<p>There are two ways to get the Node adapter:</p>
<h3 id="npm">npm</h3>
<p>Use <a href="http://npmjs.org">npm</a> to install it:</p>
<pre><code>npm install requirejs
</code></pre>
<p>This option will install the latest release.</p>
<h3 id="rjs">Download r.js</h3>
<p>If you prefer to not use npm, you can get r.js directly:</p>
<ul>
<li>Download r.js from the <a href="download.html#rjs">the download page</a> and place it in your project.</li>
<li>Get the source from the <a href="https://github.com/jrburke/r.js">r.js repo</a> and either generate the r.js via "node dist.js", or grab a snapshot from the <strong>dist</strong> directory.</li>
</ul>
<h3 id="usage">Usage<h3>
<p>These instructions assume an npm installation of 'requirejs'. If you are using the r.js file directly, replace require('requirejs') with require('./path/to/r.js'). Basic usage is:</p>
<ul>
<li>require('requirejs')</li>
<li>Pass the main js file's "require" function in the configuration to requirejs.</li>
</ul>
<p>Example:</p>
<pre><code>var requirejs = require('requirejs');
requirejs.config({
//Pass the top-level main.js/index.js require
//function to requirejs so that node modules
//are loaded relative to the top-level JS file.
nodeRequire: require
});
requirejs(['foo', 'bar'],
function (foo, bar) {
//foo and bar are loaded according to requirejs
//config, but if not found, then node's require
//is used to load the module.
});
</code></pre>
<p>Be sure to read the <a href="#2">notes in section 2</a> about configuring RequireJS so that it can load node-only modules installed via npm.</p>
<p>To see a more complete example that loads a module via RequireJS but uses Node-native modules for other things, see the <a href="https://github.com/jrburke/r.js/tree/master/tests/node/embedded">embedded test</a> in the r.js repo.</p>
<h3 id="optimizer">Using the optimizer as a node module</h3>
<p>The node module also exposes the RequireJS Optimizer as an <strong>optimize</strong> method for using the <a href="optimization.html">RequireJS optimizer</a> via a function call instead of a command line tool:</p>
<pre><code>var requirejs = require('requirejs');
var config = {
baseUrl: '../appDir/scripts',
name: 'main',
out: '../build/main-built.js'
};
requirejs.optimize(config, function (buildResponse) {
//buildResponse is just a text output of the modules
//included. Load the built file for the contents.
//Use config.out to get the optimized file contents.
var contents = fs.readFileSync(config.out, 'utf8');
});
</code></pre>
<p>This allows you to build other optimization workflows, like <a href="https://github.com/jrburke/r.js/tree/master/build/tests/http">a web builder</a> that can be used if you prefer to always develop with the "one script file included before the </body> tag" approach. The optimizer running in Node if fairly fast, but for larger projects that do not want to regenerate the build for every browser request, but just if you modify a script that is part of the build. You could use Node's fs.watchFile() to watch files and then trigger the build when a file changes.</p>
<h3 id="feedback">Feedback</h3>
<p>If you find you have a problem, and want to report it, use the <a href="http://github.com/jrburke/r.js/issues">r.js GitHub Issues page</a>.</p>
<p>If you want to discuss the RequireJS-Node integration, you can use the <a href="http://groups.google.com/group/requirejs">RequireJS Group</a>.</p>
</div>