1 | # install [![Build Status](https://travis-ci.org/benjamn/install.svg?branch=master)](https://travis-ci.org/benjamn/install) [![Greenkeeper badge](https://badges.greenkeeper.io/benjamn/install.svg)](https://greenkeeper.io/)
|
2 |
|
3 | The [CommonJS module syntax](http://wiki.commonjs.org/wiki/Modules/1.1) is one of the most widely accepted conventions in the JavaScript ecosystem. Everyone seems to agree that `require` and `exports` are a reasonable way of expressing module dependencies and interfaces, and the tools for managing modular code are getting better all the time.
|
4 |
|
5 | Much less of a consensus has developed around the best way to deliver CommonJS modules to a web browser, where the synchronous semantics of `require` pose a non-trivial implementation challenge. This module loader contributes to that confusion, yet also demonstrates that an amply-featured module loader need not stretch into the hundreds or thousands of lines.
|
6 |
|
7 | Installation
|
8 | ---
|
9 | From NPM:
|
10 |
|
11 | npm install install
|
12 |
|
13 | From GitHub:
|
14 |
|
15 | cd path/to/node_modules
|
16 | git clone git://github.com/benjamn/install.git
|
17 | cd install
|
18 | npm install .
|
19 |
|
20 | Usage
|
21 | ---
|
22 |
|
23 | The first step is to create an `install` function by calling the
|
24 | `makeInstaller` method. Note that all of the options described below are
|
25 | optional:
|
26 |
|
27 | ```js
|
28 | var install = require("install").makeInstaller({
|
29 | // Optional list of file extensions to be appended to required module
|
30 | // identifiers if they do not exactly match an installed module.
|
31 | extensions: [".js", ".json"],
|
32 |
|
33 | // If defined, the options.fallback function will be called when no
|
34 | // installed module is found for a required module identifier. Often
|
35 | // options.fallback will be implemented in terms of the native Node
|
36 | // require function, which has the ability to load binary modules.
|
37 | fallback,
|
38 |
|
39 | // Boolean flag indicating whether the installed code will be running in
|
40 | // a web browser.
|
41 | browser,
|
42 |
|
43 | // List of fields to look for in package.json files to determine the
|
44 | // main entry module of the package. The first field listed here whose
|
45 | // value is a string will be used to resolve the entry module. Defaults
|
46 | // to just ["main"], or ["browser", "main"] if options.browser is true.
|
47 | mainFields: ["browser", "main"],
|
48 | });
|
49 | ```
|
50 |
|
51 | The second step is to install some modules by passing a nested tree of
|
52 | objects and functions to the `install` function:
|
53 |
|
54 | ```js
|
55 | var require = install({
|
56 | "main.js"(require, exports, module) {
|
57 | // On the client, the "assert" module should be install-ed just like
|
58 | // any other module. On the server, since "assert" is a built-in Node
|
59 | // module, it may make sense to let the options.fallback function
|
60 | // handle such requirements. Both ways work equally well.
|
61 | var assert = require("assert");
|
62 |
|
63 | assert.strictEqual(
|
64 | // This require function uses the same lookup rules as Node, so it
|
65 | // will find "package" in the "node_modules" directory below.
|
66 | require("package").name,
|
67 | "/node_modules/package/entry.js"
|
68 | );
|
69 |
|
70 | exports.name = module.id;
|
71 | },
|
72 |
|
73 | node_modules: {
|
74 | package: {
|
75 | // If package.json is not defined, a module called "index.js" will
|
76 | // be used as the main entry point for the package. Otherwise the
|
77 | // exports.main property will identify the entry point.
|
78 | "package.json"(require, exports, module) {
|
79 | exports.name = "package";
|
80 | exports.version = "0.1.0";
|
81 | exports.main = "entry.js";
|
82 | },
|
83 |
|
84 | "entry.js"(require, exports, module) {
|
85 | exports.name = module.id;
|
86 | }
|
87 | }
|
88 | }
|
89 | });
|
90 | ```
|
91 |
|
92 | Note that the `install` function merely installs modules without
|
93 | evaluating them, so the third and final step is to `require` any entry
|
94 | point modules that you wish to evaluate:
|
95 |
|
96 | ```js
|
97 | console.log(require("./main").name);
|
98 | // => "/main.js"
|
99 | ```
|
100 |
|
101 | This is the "root" `require` function returned by the `install`
|
102 | function. If you're using the `install` package in a CommonJS environment
|
103 | like Node, be careful that you don't overwrite the `require` function
|
104 | provided by that system.
|
105 |
|
106 | If you need to change the behavior of the `module` object that each module
|
107 | function receives as its third parameter, the shared `Module` constructor
|
108 | is exposed as a property of the `install` function returned by the
|
109 | `makeInstaller` factory:
|
110 |
|
111 | ```js
|
112 | var install = makeInstaller(options);
|
113 | var proto = install.Module.prototype;
|
114 |
|
115 | // Wrap all Module.prototype.require calls with some sort of logging.
|
116 | proto.require = wrapWithLogging(proto.require);
|
117 |
|
118 | // Add a new method available to all modules via module.newMethod(...).
|
119 | proto.newMethod = function () {...};
|
120 | ```
|
121 |
|
122 | Many more examples of how to use the `install` package can be found in the
|
123 | [tests](https://github.com/benjamn/install/blob/master/test/run.js).
|