1 | # browser-resolve [![Build Status](https://travis-ci.org/browserify/browser-resolve.png?branch=master)](https://travis-ci.org/browserify/browser-resolve)
|
2 |
|
3 | node.js resolve algorithm with [browser field](https://github.com/defunctzombie/package-browser-field-spec) support.
|
4 |
|
5 | ## api
|
6 |
|
7 | ### bresolve(id, opts={}, cb)
|
8 |
|
9 | Resolve a module path and call `cb(err, path [, pkg])`
|
10 |
|
11 | Options:
|
12 |
|
13 | * `basedir` - directory to begin resolving from
|
14 | * `browser` - the 'browser' property to use from package.json (defaults to 'browser')
|
15 | * `filename` - the calling filename where the `require()` call originated (in the source)
|
16 | * `modules` - object with module id/name -> path mappings to consult before doing manual resolution (use to provide core modules)
|
17 | * `packageFilter` - transform the parsed `package.json` contents before looking at the `main` field
|
18 | * `paths` - `require.paths` array to use if nothing is found on the normal `node_modules` recursive walk
|
19 |
|
20 | Additionally, options supported by [node-resolve](https://github.com/browserify/resolve#resolveid-opts-cb) can be used.
|
21 |
|
22 | ### bresolve.sync(id, opts={})
|
23 |
|
24 | Same as the async resolve, just uses sync methods.
|
25 |
|
26 | Additionally, options supported by [node-resolve](https://github.com/browserify/resolve#resolvesyncid-opts-cb) can be used.
|
27 |
|
28 | ## basic usage
|
29 |
|
30 | you can resolve files like `require.resolve()`:
|
31 | ``` js
|
32 | var bresolve = require('browser-resolve');
|
33 | bresolve('../', { filename: __filename }, function(err, path) {
|
34 | console.log(path);
|
35 | });
|
36 | ```
|
37 |
|
38 | ```
|
39 | $ node example/resolve.js
|
40 | /home/substack/projects/browser-resolve/index.js
|
41 | ```
|
42 |
|
43 | ## core modules
|
44 |
|
45 | By default, core modules (http, dgram, etc) will return their same name as the path. If you want to have specific paths returned, specify a `modules` property in the options object.
|
46 |
|
47 | ``` js
|
48 | var shims = {
|
49 | http: '/your/path/to/http.js'
|
50 | };
|
51 |
|
52 | var bresolve = require('browser-resolve');
|
53 | bresolve('http', { modules: shims }, function(err, path) {
|
54 | console.log(path);
|
55 | });
|
56 | ```
|
57 |
|
58 | ```
|
59 | $ node example/builtin.js
|
60 | /home/substack/projects/browser-resolve/builtin/http.js
|
61 | ```
|
62 |
|
63 | ## browser field
|
64 | browser-specific versions of modules
|
65 |
|
66 | ``` json
|
67 | {
|
68 | "name": "custom",
|
69 | "version": "0.0.0",
|
70 | "browser": {
|
71 | "./main.js": "custom.js"
|
72 | }
|
73 | }
|
74 | ```
|
75 |
|
76 | ``` js
|
77 | var bresolve = require('browser-resolve');
|
78 | var parent = { filename: __dirname + '/custom/file.js' };
|
79 | bresolve('./main.js', parent, function(err, path) {
|
80 | console.log(path);
|
81 | });
|
82 | ```
|
83 |
|
84 | ```
|
85 | $ node example/custom.js
|
86 | /home/substack/projects/browser-resolve/example/custom/custom.js
|
87 | ```
|
88 |
|
89 | You can use different package.json properties for the resolution, if you want to allow packages to target different environments for example:
|
90 |
|
91 | ``` json
|
92 | {
|
93 | "browser": { "./main.js": "custom.js" },
|
94 | "chromeapp": { "./main.js": "custom-chromeapp.js" }
|
95 | }
|
96 | ```
|
97 |
|
98 | ``` js
|
99 | var bresolve = require('browser-resolve');
|
100 | var parent = { filename: __dirname + '/custom/file.js', browser: 'chromeapp' };
|
101 | bresolve('./main.js', parent, function(err, path) {
|
102 | console.log(path);
|
103 | });
|
104 | ```
|
105 |
|
106 | ```
|
107 | $ node example/custom.js
|
108 | /home/substack/projects/browser-resolve/example/custom/custom-chromeapp.js
|
109 | ```
|
110 |
|
111 | ## skip
|
112 |
|
113 | You can skip over dependencies by setting a
|
114 | [browser field](https://gist.github.com/defunctzombie/4339901)
|
115 | value to `false`:
|
116 |
|
117 | ``` json
|
118 | {
|
119 | "name": "skip",
|
120 | "version": "0.0.0",
|
121 | "browser": {
|
122 | "tar": false
|
123 | }
|
124 | }
|
125 | ```
|
126 |
|
127 | This is handy if you have code like:
|
128 |
|
129 | ``` js
|
130 | var tar = require('tar');
|
131 |
|
132 | exports.add = function (a, b) {
|
133 | return a + b;
|
134 | };
|
135 |
|
136 | exports.parse = function () {
|
137 | return tar.Parse();
|
138 | };
|
139 | ```
|
140 |
|
141 | so that `require('tar')` will just return `{}` in the browser because you don't
|
142 | intend to support the `.parse()` export in a browser environment.
|
143 |
|
144 | ``` js
|
145 | var bresolve = require('browser-resolve');
|
146 | var parent = { filename: __dirname + '/skip/main.js' };
|
147 | bresolve('tar', parent, function(err, path) {
|
148 | console.log(path);
|
149 | });
|
150 | ```
|
151 |
|
152 | ```
|
153 | $ node example/skip.js
|
154 | /home/substack/projects/browser-resolve/empty.js
|
155 | ```
|
156 |
|
157 | # license
|
158 |
|
159 | MIT
|
160 |
|
161 | # upgrade notes
|
162 |
|
163 | Prior to v1.x this library provided shims for node core modules. These have since been removed. If you want to have alternative core modules provided, use the `modules` option when calling `bresolve()`.
|
164 |
|
165 | This was done to allow package managers to choose which shims they want to use without browser-resolve being the central point of update.
|