-
Notifications
You must be signed in to change notification settings - Fork 3
/
api.html
481 lines (466 loc) · 33.5 KB
/
api.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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
<!DOCTYPE html><html><head><title>normalize.io - an ES6 module, Web Component, and SPDY/HTTP2 Push frontend development worfklow</title><meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, minimal-ui"><link rel="stylesheet" href="index.css"><link rel="stylesheet" href="https://yandex.st/highlightjs/8.0/styles/github.min.css"></head><body><div id="top-bar"><div class="container"><a id="top-bar-logo" href="./">nlz.io</a><a href="https://github.com/normalize/discussions" class="top-bar-link">discuss</a><a href="faq.html" class="top-bar-link">faq</a><a href="guide.html" class="top-bar-link">guide</a><a href="api.html" class="top-bar-link">api</a></div></div><header><div class="container"><h1>API</h1></div></header><main><div id="toc" class="Dropdown right down"><a href="#" class="Dropdown-toggle">#</a><div class="Dropdown-menu"></div></div><section><div class="container"><h2 id="triage">Triage</h2><p>Normalize is split into multiple repositories.
Most of these repositories can be found within the <a href="https://github.com/normalize">Normalize GitHub organization</a>.
When requesting features or reporting bugs,
please try to open an issue in the correct repository.</p>
<ul>
<li><a href="https://github.com/normalize/discussions">discussions</a> - a repository for any general discussions.
Don't know where to open an issue?
Want to ask for support?
Open an issue here.</li>
<li><a href="https://github.com/normalize/normalize.github.io">normalize.github.io</a> - this Normalize.IO homepage and documentation</li>
<li><a href="https://github.com/normalize/proxy.js">proxy.js</a> - the normalization proxy</li>
<li><a href="https://github.com/normalize/nlz">nlz</a> - the command line <code>nlz(1)</code> utility</li>
<li><a href="https://github.com/normalize/transforms.js">transforms.js</a> - all the transforms supported by both the proxy and <code>nlz(1)</code></li>
<li><a href="https://github.com/polyfills">The Polyfills Organization</a> - for anything having to do with browser support, polyfills, and transpilation</li>
</ul>
</div></section><section><div class="container"><h2 id="url-shorthands">URL Shorthands</h2><p>Typing <code>https://nlz.io/</code> everywhere becomes tedious quickly,
so Normalize allows you to use shorthands for dependencies.
Shorthands simply expand to the long Normalize URLs.
However, due to the wide remote support Normalize provides,
shorthands require a certain degree of specificity.</p>
<p>However, shorthands can only be used if:</p>
<ol>
<li>You use a build process, <code>nlz build</code></li>
<li>You use a Normalizer server such as <code>koa-normalize</code></li>
<li>You use a custom client-side ES6 module loader</li>
</ol>
<p>Thus, shorthands are second-class citizens.
Normalize will eventually provide a custom module loader for these shorthands.</p>
<h3 id="the-law-of-shorthands">The Law of Shorthands</h3>
<ol>
<li>You shan't use shorthands in CSS and HTML as they do not allow custom loaders.</li>
<li>You shan't use shorthands in libraries,
only applications where you can expect a custom module loader to be used.
Creating libraries with shorthands is too vendor-specific.
URLs should always work in any environment!</li>
<li><code>@</code> is used for versions and commits. Do <strong>not</strong> use <code>#</code>.</li>
</ol>
<h3 id="shorthands">Shorthands</h3>
<h4 id="extensions">Extensions</h4>
<p>Files that end with <code>/</code> expand to <code>/index.js</code>:</p>
<pre><code>./<span class="hljs-keyword">lib</span>/ => ./<span class="hljs-keyword">lib</span>/index.js
</code></pre><p>Files that do not end with <code>.js</code> simply have <code>.js</code> appended:</p>
<pre><code>./<span class="hljs-keyword">index</span> => ./<span class="hljs-keyword">index</span>.js
</code></pre><h4 id="npm">npm</h4>
<p><code><module>@<version>/<file...></code> resolves to <code>https://nlz.io/npm/-/<module>/<version>/<file...></code>:</p>
<pre><code>emitter<span class="hljs-variable">@1</span> => <span class="hljs-regexp">/npm/</span>-<span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/index.js
emitter<span class="hljs-variable">@1</span>/ => <span class="hljs-regexp">/npm/</span>-<span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/index.js
emitter<span class="hljs-variable">@1</span>/something => <span class="hljs-regexp">/npm/</span>-<span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/something.js
</code></pre><p>Namespaces are prefixed with <code>@<org></code>,
i.e. <code>@<org>/<module>@<version>/<file...></code>:</p>
<pre><code><span class="hljs-variable">@nlz</span>/emitter<span class="hljs-variable">@1</span> => <span class="hljs-regexp">/npm/nlz</span><span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/index.js
<span class="hljs-variable">@nlz</span>/emitter<span class="hljs-variable">@1</span>/ => <span class="hljs-regexp">/npm/nlz</span><span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/index.js
<span class="hljs-variable">@nlz</span>/emitter<span class="hljs-variable">@1</span>/something => <span class="hljs-regexp">/npm/nlz</span><span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/something.js
</code></pre><p>When prefixed with <code>@org</code>, the <code>@<version></code> is optional:</p>
<pre><code><span class="hljs-property">@nlz</span><span class="hljs-regexp">/emitter => /npm/nlz/emitter/</span>*/index.js
<span class="hljs-property">@nlz</span><span class="hljs-regexp">/emitter/</span><span class="hljs-function"> =></span> <span class="hljs-regexp">/npm/nlz/emitter/</span>*/index.js
<span class="hljs-property">@nlz</span><span class="hljs-regexp">/emitter/something => /npm/nlz/emitter/</span>*/something.js
</code></pre><p>npm shorthands may always be prefixed with <code>npm:</code>:</p>
<pre><code><span class="hljs-symbol">npm:</span>emitter<span class="hljs-variable">@1</span> => <span class="hljs-regexp">/npm/</span>-<span class="hljs-regexp">/emitter/</span><span class="hljs-number">1</span>/index.js
</code></pre><h4 id="github">GitHub</h4>
<p><code><user>/<project>@<version>/<file...></code> resolves to <code>https://nlz.io/<user>/<project>/<version>/<file...></code>:</p>
<pre><code>component/emitter<span class="hljs-variable">@1</span> => <span class="hljs-regexp">/component/emitter</span><span class="hljs-regexp">/1/index</span>.js
component/emitter<span class="hljs-variable">@1</span>/lib => <span class="hljs-regexp">/component/emitter</span><span class="hljs-regexp">/1/lib</span><span class="hljs-regexp">/index.js</span>
</code></pre><p>Note that <code>@<version></code> here is required for the shorthand,
otherwise it could be a file.</p>
<h4 id="everything-else">Everything Else</h4>
<p>All other remotes can be abbreviated to:</p>
<pre><code><remote><span class="hljs-symbol">:<user>/<project></span>@<version><span class="hljs-regexp">/<file...></span>
</code></pre><p>Where:</p>
<ul>
<li><code>remote</code> is the remote name or alias.</li>
<li><code>user</code> is optional if the remote has a global namespace (i.e. <code>npm</code>)</li>
<li><code>project</code> - the name of the project/module/package</li>
<li><code>version</code> - is optional, defaulting to <code>*</code></li>
<li><code>file</code> - can be completely empty, defaulting to <code>/index.js</code></li>
</ul>
<p>Some remotes, such as npm, have or will have namespaces.
However, it will be treated as if it does not as most modules do not use namespaces.
As you can see from above, npm modules have a custom shorthand syntax due to this pecularity.</p>
</div></section><section><div class="container"><h2 id="nlz-cli">nlz(1)</h2><p><code>nlz(1)</code> is the stopgap CLI tool for normalization proxies.
Eventually, <code>nlz build(1)</code> will be completely optional,
and <code>nlz(1)</code> will primarily be a CLI tool for inspecting your app/component's dependency tree.</p>
<h3 id="installation">Installation</h3>
<p>Currently, you must install <code>nlz(1)</code> with <code>npm(1)</code>:</p>
<pre><code class="lang-bash">npm <span class="hljs-keyword">install</span> -g nlz
</code></pre>
<p><code>nlz(1)</code> supports node v0.10+,
but you should use node v0.11+ for better performance
as generators are extensively used in the source code.</p>
<p>Be sure to globally install any transforms you'd like to use as well.</p>
<pre><code class="lang-bash">npm <span class="hljs-keyword">install</span> -g jade marked
</code></pre>
<h3 id="normalize-manifest-json">normalize-manifest.json</h3>
<p>When building, a <code>normalize-manifest.json</code> file is created.
Be sure to add this file to your <code>.gitignore</code>!
This JSON file is used for various purposes:</p>
<ul>
<li>You can use this to inspect all the files in the build as well as its
dependency tree. <code>nlz(1)</code> uses this file in other commands,
such as <code>nlz-dependencies(1)</code>, to help inspect the files and the dependency tree.</li>
<li>You may use this file to create your own SPDY push server or middleware.</li>
</ul>
<h3 id="nlz-build-nlz-watch">nlz build, nlz watch</h3>
<p>These are the primary build command.
You may think of it as <a href="http://browserify.org">browserify</a>'s build command
with multiple entry point support
as well as CSS and HTML file support.</p>
<p>Most of these parameters and options can be set via <code>.nlzrc</code>,
allowing developers to simply run <code>nlz build --watch</code>.</p>
<p>Note that the builder <strong>does not support buildilng web components!</strong>
This is essentially impossible to do.
Only use web components in a SPDY environment.</p>
<h4 id="entry-points">Entry Points</h4>
<pre><code class="lang-bash">nlz build [entrypoints...]
<span class="hljs-comment">// will build to build/index.js and build/index.css, respectively</span>
nlz build <span class="hljs-keyword">client</span>/<span class="hljs-keyword">index</span>.js <span class="hljs-keyword">client</span>/<span class="hljs-keyword">index</span>.css
</code></pre>
<h4 id="-">-</h4>
<p>If you are only building a single entry point, you can
stream the result through <code>stdout</code> with the <code>-</code> option:</p>
<pre><code class="lang-bash">nlz build index<span class="hljs-preprocessor">.js</span> - > index<span class="hljs-preprocessor">.built</span><span class="hljs-preprocessor">.js</span>
</code></pre>
<p>Stdin is not supported.</p>
<h4 id="-out-o">--out, -o</h4>
<p>The destination folder, defaulting to <code>build/</code>.
The destination file will be the same name as the entry point's file name.</p>
<pre><code class="lang-bash">nlz build <span class="hljs-keyword">client</span>/<span class="hljs-keyword">index</span>.js --out <span class="hljs-keyword">public</span>
</code></pre>
<h4 id="-watch-w">--watch, -w</h4>
<p>Watch the source files for changes and rebuild automatically.
You <strong>should</strong> use this as rebuilds are fast and incremental.
Simply loading <code>nlz(1)</code> takes a considerable amount of time,
especially if you use a lot of transformations.</p>
<pre><code class="lang-bash">nlz build <span class="hljs-keyword">client</span>/<span class="hljs-keyword">index</span>.js --watch
</code></pre>
<p>This is aliased as <code>nlz watch</code>.</p>
<h3 id="-standalone-s">--standalone, -s</h3>
<p>Create a standalone, UMD-wrapped JS bundle.</p>
<h3 id="nlz-manifest">nlz manifest</h3>
<p>Similar to <code>nlz-build(1)</code>,
except no files will actually be built.
Use this just to create <code>normalize-manifest.json</code>,
which is required for the dependency inspection commands.</p>
<h4 id="-no-min-m">--no-min, -M</h4>
<p>By default, <code>nlz-manifest(1)</code> calculates the minified size of assets.
This gives each file a better representation of its size
in the final bundle.
However, this takes a long time compute.
Set <code>--no-min</code> to disable minified size calculations.</p>
<h3 id="nlz-dependencies">nlz dependencies</h3>
<p>List all the dependencies,
included nested ones,
of a single entry point.
Unlike other "ls" type commands,
this command does not create an incredibly nested tree.
The file size is listed next to each file.</p>
<pre><code class="lang-bash">nlz dependencies <entrypoint>
<span class="hljs-comment">// list the dependencies of a single file</span>
nlz dependencies <span class="hljs-keyword">index</span>.js
</code></pre>
<p><img src="images/nlz-dependencies.png" alt="nlz-dependencies(1)"></p>
<h4 id="-remotes-r">--remotes, -r</h4>
<p>By default, dependencies of remote dependencies are not traversed.
To include them, use the <code>--remotes</code> option.</p>
<h3 id="nlz-dependents">nlz dependents</h3>
<p>This command is similar to <code>nlz-dependencies(1)</code>,
except shows all the nested dependents of a particular file.
Any file included in the manifest could be used as an entry point.</p>
<pre><code class="lang-bash">nlz dependencies <entrypoint>
// list <span class="hljs-keyword">all</span> the nested dependents <span class="hljs-keyword">of</span> <span class="hljs-keyword">component</span>/emitter@<span class="hljs-number">1.1</span><span class="hljs-number">.2</span>
nlz dependents <span class="hljs-keyword">component</span>/emitter@<span class="hljs-number">1.1</span><span class="hljs-number">.2</span>
</code></pre>
<p><img src="images/nlz-dependents.png" alt="nlz-dependents(1)"></p>
<h3 id="nlz-duplicates">nlz duplicates</h3>
<p>Lists all remote dependents of which you use more than a single version.
In frontend development,
you don't want duplicate dependencies as it means unnecessary bandwidth usage.</p>
<pre><code class="lang-bash"><span class="hljs-comment">// list the duplicate dependencies</span>
<span class="hljs-comment">// based on the current normalize-manifest.json</span>
nlz duplicates
</code></pre>
<p><code>nlz-duplicates(1)</code> will show:</p>
<ul>
<li>The "redundancy size", or the estimated bytes you could save by de-duping each dependency.</li>
<li>Each version of the dependency used.</li>
<li>Each file of each dependency used, it's size, and its dependents.</li>
</ul>
<p><img src="images/nlz-duplicates.png" alt="nlz-duplicates(1)"></p>
<h3 id="nlz-size">nlz size</h3>
<p>List the sizes of an entry point and its dependencies,
as well as its combined size.
Useful for gauging which dependency is the largest.</p>
<pre><code class="lang-bash">nlz size <entrypoint>
<span class="hljs-regexp">//</span> get the size of test/<span class="hljs-keyword">index</span>.js <span class="hljs-keyword">and</span> its dependencies
nlz size test/<span class="hljs-keyword">index</span>.js
</code></pre>
<p><img src="images/nlz-size.png" alt="nlz-size(1)"></p>
<h4 id="-exts-e">--exts, -e</h4>
<p>Filter the files by a comma-separated list of extensions.
For example:</p>
<pre><code class="lang-bash">nlz size <span class="hljs-operator">-e</span> js,css,svg test/index.js
</code></pre>
<h4 id="-threshold-t">--threshold, -t</h4>
<p>Only show files larger than a <code>threshold</code> file size.
For example, only list files larger than <code>1kb</code>:</p>
<pre><code class="lang-bash">nlz size -t <span class="hljs-number">1</span>kb test/<span class="hljs-keyword">index</span>.js
</code></pre>
<h3 id="nlz-graph">nlz graph</h3>
<p>Create a graph of your dependency tree. Run <code>nlz graph -h</code> for more details.</p>
</div></section><section><div class="container"><h2 id="nlzrc">.nlzrc</h2><p><code>.nlzrc</code> is an optional JSON configuration file for local environments.
It's completely optional.
You may have a global, <code>.nlzrc</code> configuration for your computer as well as local <code>.nlzrc</code> configuration for each app.
For example, you might want to point all your requests to a proxy on your network instead of <a href="https://nlz.io">https://nlz.io</a>.</p>
<h3 id="-entrypoints">.entrypoints</h3>
<p>The entry points for the build.
This allows you to not specify the entry points every time you run <code>nlz build(1)</code>.</p>
<pre><code class="lang-json">{
"<span class="hljs-attribute">entrypoints</span>": <span class="hljs-value">[<span class="hljs-string">"client/index.js"</span>, <span class="hljs-string">"client/index.css"</span>]
</span>}
</code></pre>
<p>You may also use objects if you want to set custom options on each entry point:</p>
<pre><code class="lang-json">{
"<span class="hljs-attribute">entrypoints</span>": <span class="hljs-value">{
"<span class="hljs-attribute">client/index.js</span>": <span class="hljs-value">{
}</span>,
"<span class="hljs-attribute">client/index.css</span>": <span class="hljs-value">{
}
</span>}
</span>}
</code></pre>
<h3 id="-proxy-and-self-signed">.proxy and .self-signed</h3>
<pre><code class="lang-json">{
"<span class="hljs-attribute">proxy</span>": <span class="hljs-value"><span class="hljs-string">"localhost:8888"</span></span>,
"<span class="hljs-attribute">self-signed</span>": <span class="hljs-value"><span class="hljs-literal">true</span>
</span>}
</code></pre>
<p>This is to set a custom proxy other than <a href="https://nlz.io">https://nlz.io</a>.
<code>proxy</code> should be the full host, including the port.
Set <code>self-signed</code> to <code>true</code> if the proxy is using a self-signed certification,
otherwise an error will be thrown.
Remember, proxies must always use SSL.</p>
<h3 id="-minifiedlength-true">.minifiedLength = true</h3>
<p>Option whether to include each file's minified length in the manifest.
This takes a long time to calculate,
so is only recommended when you do <code>--watch</code>.
Set to <code>false</code> if you never want to calculate this.</p>
<h3 id="-directory-repositories-">.directory = "repositories"</h3>
<pre><code class="lang-json">{
"<span class="hljs-attribute">directory</span>": <span class="hljs-value"><span class="hljs-string">"/User/jong/.repositories"</span>
</span>}
</code></pre>
<p>By default, all files are stored to <code>process.cwd() + '/repositories'</code>.
Thus, every app or component you work on will have its own <code>directory</code> folder.
This may be less than ideal for you as you'll have multiple copies.</p>
<p>You may optionally set this directory to a global directory like <code>~/.repositories</code>
so that every app or component you work on share the same files.
It will also make installations a little faster.</p>
<h3 id="-transform-normalize-transforms-">.transform = "normalize-transforms"</h3>
<p>Use a custom transform function instead of those supplied by Normalize.
See <a href="https://github.com/normalize/transforms.js">normalize-transforms</a> for more information.</p>
<h3 id="-transforms-">.transforms = {}</h3>
<p>Pass options to the transform function mentioned above,
which is <a href="https://github.com/normalize/transforms.js">normalize-transforms</a>.</p>
<h3 id="-manifest-normalize-manifest-json-">.manifest = "normalize-manifest.json"</h3>
<p>This allows you to use a custom <code>normalize-manifest.json</code> file name.</p>
</div></section><section><div class="container"><h2 id="transforms">Transforms</h2><p>These are all the transforms available for both the normalization proxy and <code>nlz-build(1)</code>.</p>
<p>Unlike other bundlers and build systems,
adapters transforms are included automatically.
There are a couple of reasons for this:</p>
<ul>
<li>This middleware system is a more complicated than other middleware systems:<ul>
<li>The use of Koa-based upstream/downstream is quite complex</li>
<li>Order of middleware is very important</li>
<li>Transforms are not orthogonal to another,
so we have to make sure each plugin interacts with each other well.</li>
</ul>
</li>
<li>The purpose of normalization is for everyone to be on the same page.
It's counter productive to have different semantics for the same transform across applications.</li>
</ul>
<p>However, for both the proxy and for <code>nlz(1)</code>,
<strong>you must install each underlying library yourself</strong>.
If all libraries were included,
then <code>nlz(1)</code> will quickly grow to <code>100mb+</code> as well as have a very long install time
due to all the C/C++ addons these libraries use.
For example, to use the Jade transform, you must also install Jade globally:</p>
<pre><code class="lang-bash"><span class="hljs-preprocessor"># Install Normalize</span>
npm i -g nlz
<span class="hljs-preprocessor"># Install Jade as well</span>
npm i -g jade
</code></pre>
<p>PRs for additional transforms are welcomed as long as there's a valid use-case and people would actually use it.
Feel free to create feature requests and pull requests in the <a href="https://github.com/normalize/transforms.js">transform.js</a> repository.</p>
<h3 id="how-transforms-work">How Transforms Work</h3>
<p>Given a source file such as <code>template.html</code>,
the walker transforms the file based on additional <code>.<extensions></code>.
For example, <code>template.html.js</code> will export the HTML string as a JS string.
This is superior to other transform systems because:</p>
<ul>
<li>It's compatible with HTTP servers</li>
<li>The transforms used are explicitly shown</li>
<li>It allows you to use the same source file in multiple ways without configuration</li>
</ul>
<p>For example, <code>template.jade.js</code> returns a jade render function whereas <code>template.jade.html.js</code> returns the jade template as a compiled string.</p>
<p>You can also compose multiple transforms together.
For example, <code>.jade.html.js</code> is a composition of <code>.jade.html</code> and <code>.html.js</code>.</p>
<p>Unlike other build systems,
transforms have the ability to inject dependencies into your application and automatically install them,
making development easier in general.
For example, to use <code>.jade.js</code>, you need the <a href="https://github.com/facebook/regenerator/blob/master/runtime/dev.js">jade runtime</a>.
The Jade transform will automatically inject the runtime by compiling your jade template to something like this:</p>
<pre><code class="lang-js">import jade from <span class="hljs-string">'https://nlz.io/github/visionmedia/jade/1/lib/runtime.js'</span>
export <span class="hljs-keyword">default</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">template</span><span class="hljs-params">(locals)</span> {</span>
<span class="hljs-comment">// compiled jade</span>
}
</code></pre>
<h3 id="css-transforms">CSS Transforms</h3>
<h4 id="-less-css-"><code>less.css</code></h4>
<p>Convert LESS files to CSS.</p>
<pre><code class="lang-css"><span class="hljs-at_rule">@<span class="hljs-keyword">import</span> <span class="hljs-string">'styles.less.css'</span></span>;
</code></pre>
<h4 id="-sass-scss-css-"><code>(sass|scss).css</code></h4>
<p>Convert SASS files to CSS.</p>
<pre><code class="lang-css"><span class="hljs-at_rule">@<span class="hljs-keyword">import</span> <span class="hljs-string">'styles.sass.css'</span></span>;
<span class="hljs-at_rule">@<span class="hljs-keyword">import</span> <span class="hljs-string">'styles.scss.css'</span></span>;
</code></pre>
<h4 id="-stylus-css-"><code>stylus.css</code></h4>
<p>Convert Stylus files to CSS.</p>
<pre><code class="lang-css"><span class="hljs-at_rule">@<span class="hljs-keyword">import</span> <span class="hljs-string">'styles.styl.css'</span></span>;
</code></pre>
<h3 id="js-transforms">JS Transforms</h3>
<h4 id="-mime-text-js-"><code>.<mime:text/*>.js</code></h4>
<p>All extensions whose corresponding MIME type is <code>text/*</code> are automatically transformed to a JS string using <code>JSON.stringify()</code> unless superceded by another transform.</p>
<pre><code class="lang-js">import <span class="hljs-keyword">text</span> <span class="hljs-built_in">from</span> <span class="hljs-string">'something.txt'</span>
var el = document.createTextNode()
el.textContent = <span class="hljs-keyword">text</span>
</code></pre>
<h4 id="-json-js-"><code>.json.js</code></h4>
<p>Transforms JSON files to a JS object.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> <span class="hljs-built_in">data</span> from <span class="hljs-string">'data.json'</span>
<span class="hljs-built_in">var</span> name <span class="hljs-subst">=</span> <span class="hljs-built_in">data</span><span class="hljs-built_in">.</span>name
</code></pre>
<h4 id="-coffee-js-"><code>.coffee.js</code></h4>
<p>Transforms a CoffeeScript file to JS.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> fn <span class="hljs-keyword">from</span> <span class="hljs-string">'thing.coffee'</span>
fn()
</code></pre>
<h3 id="template-transforms">Template Transforms</h3>
<h4 id="-jade-html-"><code>.jade.html</code></h4>
<p>Compile <a href="https://github.com/visionmedia/jade">jade</a> templates to an HTML string.
For example, combined with the <code>.<mime:text/*>.js</code> transform:</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> html <span class="hljs-keyword">from</span> <span class="hljs-string">'template.html'</span>
el.innerHTML = html
</code></pre>
<h4 id="-jade-js-"><code>.jade.js</code></h4>
<p>Compile <a href="https://github.com/visionmedia/jade">jade</a> templates to a function.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> render <span class="hljs-keyword">from</span> <span class="hljs-string">'template.jade'</span>
<span class="hljs-keyword">import</span> data <span class="hljs-keyword">from</span> <span class="hljs-string">'data.json'</span>
el.innerHTML = render(data)
</code></pre>
<h4 id="-md-markdown-html-"><code>.(md|markdown).html</code></h4>
<p>Compile markdown templates to an HTML string using <a href="https://github.com/chjj/marked">marked</a>.
Note that without <code>.html</code>, the actual markdown is returned.</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> html <span class="hljs-keyword">from</span> <span class="hljs-string">'article.md.html'</span>
el.innerHTML = html
</code></pre>
<h4 id="-jsx-js-"><code>.jsx.js</code></h4>
<p>Compile <a href="http://facebook.github.io/react/">React</a> <code>.jsx</code> templates to JS.</p>
<h4 id="-html-domify-js-"><code>.html.domify.js</code></h4>
<p>Compile an HTML string to an element using <a href="https://github.com/component/domify">domify</a>.
This is useful for web components and templates.</p>
<pre><code class="lang-js"><span class="hljs-reserved">import</span> template from <span class="hljs-string">'template.html.domify'</span>
<span class="hljs-built_in">document</span>.body.appendChild(template.cloneNode(<span class="hljs-literal">true</span>))
</code></pre>
</div></section><section><div class="container"><h2 id="proxy">Normalization Proxy</h2><p>This is the public HTTP API for <a href="https://nlz.io">https://nlz.io</a> as well as any <a href="https://github.com/normalize/proxy.js">normalize-proxy</a>.
If you're interested in setting up your own proxy,
consult the <a href="https://github.com/normalize/proxy.js">normalize-proxy repository</a> itself.</p>
<h3 id="url-structure">URL Structure</h3>
<p>All URLs have the form:</p>
<pre><code>https://nlz.io/<span class="hljs-tag"><<span class="hljs-title">remote</span>></span>/<span class="hljs-tag"><<span class="hljs-title">user</span>></span>/<span class="hljs-tag"><<span class="hljs-title">project</span>></span>/<span class="hljs-tag"><<span class="hljs-title">version</span>></span>/<span class="hljs-tag"><<span class="hljs-title">file...</span>></span>
</code></pre><p>Different proxies will have different hostnames.
The <code>version</code> and <code>file</code> may not be included in some end points.</p>
<h4 id="protocol">Protocol</h4>
<p>Every proxy <strong>must</strong> serve via HTTPS and SPDY/HTTPv2,
even with a self-signed certificate.
The primary reason is that some browsers intend to not support SPDY without SSL.</p>
<h4 id="remote">Remote</h4>
<p>A supported remote's name, for example <code>github/</code>.</p>
<p>Aliases will also be supported and will simply redirect to the canonical short name.
For example, <code>github.com</code> and <code>raw.githubusercontent.com</code> would redirect to <code>github</code>.</p>
<h4 id="user">User</h4>
<p>The owner of a repository.
If the remote does not have a namespace, the user should simply be <code>-</code>.</p>
<pre><code><span class="hljs-symbol">https:</span>/<span class="hljs-regexp">/nlz.io/npm</span><span class="hljs-regexp">/-/escape</span>-regexp/*<span class="hljs-regexp">/index.js</span>
</code></pre><h4 id="project">Project</h4>
<p>The name of the project/module/component.</p>
<h4 id="version">Version</h4>
<p>Any version as defined by <a href="http://semver.org">http://semver.org</a>.
You should not include leading <code>v</code>s and <code>=</code> in single versions otherwise a redirect will occur.</p>
<p>Versions can also be git branches and commit SHAs if the remote is accessed via git
and will redirect to the full commit sha.</p>
<h3 id="api-end-points">API End Points</h3>
<h4 id="get-file">GET File</h4>
<p>You may still <code>GET</code> files directly, even with transforms.
All of the files' dependencies will be SPDY pushed to the client.
A redirect may be returned as a response.
If this is the case, the redirect location will be SPDY pushed as well.</p>
<p>Each file can have the following query strings.
These are only valid when <strong>exact</strong>, so don't include a trailing <code>=</code>.
Only one query string can be used at a time:</p>
<ul>
<li><code>?source</code> - return/redirect the source file and its dependencies all without any transformations applied. Useful for building server-side.</li>
</ul>
<p>If any of these query strings are included,
then all the pushed dependencies will also include the same query string.</p>
<h4 id="get-pull">GET pull</h4>
<pre><code>GET https://nlz.io/<span class="hljs-tag"><<span class="hljs-title">remote</span>></span>/<span class="hljs-tag"><<span class="hljs-title">user</span>></span>/<span class="hljs-tag"><<span class="hljs-title">project</span>></span>/pull
</code></pre><p>For git remotes, this will <code>git fetch -f</code> the entire repository to the proxy,
updating all the versions.</p>
<p>For non-git remotes, this will check for the latest version of the project
and install it locally.</p>
<p>You may consider this the optional "publish" step of Normalize.IO.</p>
<h4 id="get-versions-json">GET versions.json</h4>
<pre><code>GET https://nlz.io/<span class="hljs-tag"><<span class="hljs-title">remote</span>></span>/<span class="hljs-tag"><<span class="hljs-title">user</span>></span>/<span class="hljs-tag"><<span class="hljs-title">project</span>></span>/versions.json
</code></pre><p>Will return an array of versions that are currently available on the proxy.
If no versions are installed,
a <code>404</code> and an empty array will be returned.</p>
<p>If you pushed a new version of a package,
but the proxy has not installed it yet,
simply install it by hitting the <code>pull</code> entry point or <code>GET</code> any file.</p>
<blockquote>
<p>Note: he semantics of this endpoint is subject to change.
In particular, it should return all available versions on the remote.</p>
</blockquote>
<h4 id="get-proxy-json">GET proxy.json</h4>
<pre><code class="lang-js">GET https://nlz<span class="hljs-preprocessor">.io</span>/proxy<span class="hljs-preprocessor">.json</span>
</code></pre>
<p>Returns relevant information about the proxy including hostname, version, and supported remotes.</p>
<h4 id="get-polyfill-js">GET polyfill.js</h4>
<p>Creates a polyfill bundle based on the client's user agent.
See <a href="https://github.com/polyfills/polyfills">polyfills/polyfills</a> for more details.</p>
<h3 id="normalization">Normalization</h3>
<p>Packages are "normalized" based on these JSON files in descending priority.</p>
<ol>
<li><code>component.json</code></li>
<li><code>package.json</code></li>
</ol>
<p>This is particularly important if you compile your module for one package manager but not the others.
Thus, if you have to compile your module for a package manager,
compile it for <code>bower</code>.</p>
<h4 id="package-json">package.json</h4>
<p>Only <code>npm</code> and <code>github</code>-style dependencies are supported.
Only semantic versions are supported - versions that have weird suffixes will be ignored.
Other types of dependencies such as tarballs will be ignored.</p>
<h4 id="circular-dependencies">Circular Dependencies</h4>
<p>Modules that must be normalized and have circular dependencies are not supported.
In fact, these modules may actually mess up the proxy.
Please don't create circular dependencies!
Use <code>devDependencies</code> or something instead.</p>
</div></section></main><footer><div class="container"><div id="footer-badges"><script data-gittip-username="jonathanong" src="https://gttp.co/v1.js" async></script></div><ul id="footer-links"><li>Jonathan Ong © 2014</li><li><a href="http://jongleberry.com">jongleberry.com</a></li><li><a href="https://github.com/jonathanong">@jonathanong</a></li><li><a href="https://twitter.com/jongleberry">@jongleberry</a></li><li><a href="mailto:[email protected]">[email protected]</a></li></ul></div></footer><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-7367759-13', 'normalize.github.io');
ga('send', 'pageview');
</script><script src="http://yandex.st/highlightjs/8.0/highlight.min.js"></script><script src="index.js"></script></body></html>