/
requirements.html
116 lines (87 loc) · 7.34 KB
/
requirements.html
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
<div id="directory" class="section">
<h1>RequireJS Requirements</h1>
<ul class="index mono">
<li class="hbox">
<a href="#1">Get RequireJS</a><span class="spacer boxFlex"></span><span class="sect">§ 1</span>
</li>
<li class="hbox">
<a href="#2">Go with the grain of the browser</a><span class="spacer boxFlex"></span><span class="sect">§ 2</span>
</li>
<li class="hbox">
<a href="#3">Load code before and after page load</a><span class="spacer boxFlex"></span><span class="sect">§ 3</span>
</li>
<li class="hbox">
<a href="#4">The loader should be able to load nested dependencies</a><span class="spacer boxFlex"></span><span class="sect">§ 4</span>
</li>
<li class="hbox">
<a href="#5">Modules need to be evaluated according to dependencies</a><span class="spacer boxFlex"></span><span class="sect">§ 5</span>
</li>
<li class="hbox">
<a href="#6">The module format should be compact</a><span class="spacer boxFlex"></span><span class="sect">§ 6</span>
</li>
<li class="hbox">
<a href="#7">Have a streamlined core loader, but allow for the future</a><span class="spacer boxFlex"></span><span class="sect">§ 7</span>
</li>
<li class="hbox">
<a href="#8">Allow modules to keep a clean global namespace</a><span class="spacer boxFlex"></span><span class="sect">§ 8</span>
</li>
<li class="hbox">
<a href="#9">Load any script</a><span class="spacer boxFlex"></span><span class="sect">§ 9</span>
</li>
<li class="hbox">
<a href="#10">Allow for performance upgrades</a><span class="spacer boxFlex"></span><span class="sect">§ 10</span>
</li>
</ul>
<span class="note">Note: RequireJS is designed to meet the following requirements:</span>
</div>
<div class="section">
<h2><a name="1">Go with the grain of the browser</a><span class="sectionMark">§ 1</span></h2>
<p>XMLHttpRequest(XHR) loaders are limited to the same domain as the page, and make debugging harder. Certain browsers allow cross-domain XHR calls and better conventions for debugging when eval is used, but support is inconsistent across browsers.</p>
<p>Eval-based loaders should be avoided since eval is not a JavaScript best practice and it is not allowed in some environments. There is a time and place for eval, but a module loader can do better than to use it.</p>
<p>A server process that transforms scripts on the fly should also not be needed. Getting everyone to use the same server process or even making specs for a common format they can all emit is more overhead, more stuff to write. Front-end developers have a long established practice of being able to author plain text files and having them load in the browser without a bunch of server hardware.</p>
<p>Scripts loaded via script tags work everywhere and work across domains. It is a much simpler loading style that uses the natural way browsers load scripts.</p>
</div>
<div class="section">
<h2><a name="2">Load code before and after page load</a><span class="sectionMark">§ 2</span></h2>
<p>The same system should be usable before and after page load. Delaying loading of code until a later page action is a key performance benefit.</p>
</div>
<div class="section">
<h2><a name="3">Scripts should be able to specify dependencies</a><span class="sectionMark">§ 3</span></h2>
<p>It is very easy for a project to go beyond needing a couple of scripts. It is hard to manually track all the dependencies and the correct loading order. A script should be able to specify its immediate dependencies. The developer should not have to worry about what those dependencies need to load and work out the correct loading order.</p>
</div>
<div class="section">
<h2><a name="4">The loader should be able to load nested dependencies</a><span class="sectionMark">§ 4</span></h2>
<p>If each module specifies its own direct dependencies, the loader should be able to work out the correct dependencies across the whole system, even nested dependencies, for dependencies of dependencies.</p>
</div>
<div class="section">
<h2><a name="5">Scripts can be evaluated out of order, but modules need to be evaluated according to dependencies</a><span class="sectionMark">§ 5</span></h2>
<p>Using the browser-native script loading that has nested dependency resolution and works after page load means that scripts will need to be loaded at least part of the time via using appendChild for script elements.</p>
<p>IE and WebKit will execute scripts added via appendChild out of DOM order, they
execute them in network receive order. Even if they executed scripts in the order
they were added to the DOM, dependencies for a module are discovered after
the module script has been loaded, so scripts for the dependencies will always be added
after the script that needs them.</p>
<p>This leads to constructing a module format for a script, one that puts the bulk of the script in a function, with its dependencies specified outside of that function wrapper. This allows scripts to be evaluated out of order by the browser, but gives the chance to properly work out the dependencies, then call the function wrappers in the right sequence to bring the scripts into being.</p>
</div>
<div class="section">
<h2><a name="6">The module format should be compact</a><span class="sectionMark">§ 6</span></h2>
<p>Boilerplate code is a pain. However a function wrapper is needed as part of the boilerplate. Prefer making the boilerplate as terse as possible, to allow easy hand-coding by developers. Avoid overly-explicit module formats that use a name/value pair for each property, since developer will have to code these by hand.</p>
</div>
<div class="section">
<h2><a name="7">Have a streamlined core loader, but allow for the future</a><span class="sectionMark">§ 7</span></h2>
<p>The core of the loader, module format support with nested dependency resolution, should be compact, but allow for plugins to expand the concept of dependencies and what it means to load them.</p>
<p>In Dojo, it is common to need i18n string bundles and text strings of HTML for widget constructions. Allow the loader to be able to load these things, but as plugins, so the core stays lightweight.</p>
</div>
<div class="section">
<h2><a name="8">Allow modules to keep a clean global namespace</a><span class="sectionMark">§ 8</span></h2>
<p>As projects get bigger, it is more common to need to load two versions of a module in a page. This should be possible by allowing a module system that does not define modules in the global namespace.</p>
<p>If a module wants to work with the global namespace, that is normally easy to allow in a module spec. The harder part is constructing a format that works well to avoid the global namespace.</p>
</div>
<div class="section">
<h2><a name="9">Load any script</a><span class="sectionMark">§ 9</span></h2>
<p>Not all scripts will be using the module format. Allow existing scripts to be loaded and treated as dependencies.</p>
</div>
<div class="section">
<h2><a name="10">Allow for performance upgrades</a><span class="sectionMark">§ 10</span></h2>
<p>This mainly means having a build system that can combine and optimize modules. It also means the loader should allow loading a script with multiple modules defined in it and only fetch dependencies that are not already included in that script file.</p>
</div>