README.md (3790B)
1 # browser-resolve [](https://travis-ci.org/defunctzombie/node-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 ### resolve(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 Options supported by [node-resolve](https://github.com/substack/node-resolve#resolveid-opts-cb) can be used. 21 22 ### resolve.sync(id, opts={}) 23 24 Same as the async resolve, just uses sync methods. 25 26 Options supported by [node-resolve](https://github.com/substack/node-resolve#resolvesyncid-opts) `sync` can be used. 27 28 ## basic usage 29 30 you can resolve files like `require.resolve()`: 31 ``` js 32 var resolve = require('browser-resolve'); 33 resolve('../', { filename: __filename }, function(err, path) { 34 console.log(path); 35 }); 36 ``` 37 38 ``` 39 $ node example/resolve.js 40 /home/substack/projects/node-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 resolve = require('browser-resolve'); 53 resolve('fs', { modules: shims }, function(err, path) { 54 console.log(path); 55 }); 56 ``` 57 58 ``` 59 $ node example/builtin.js 60 /home/substack/projects/node-browser-resolve/builtin/fs.js 61 ``` 62 63 ## browser field 64 browser-specific versions of modules 65 66 ``` js 67 { 68 "name": "custom", 69 "version": "0.0.0", 70 "browser": { 71 "./main.js": "custom.js" 72 }, 73 "chromeapp": { 74 "./main.js": "custom-chromeapp.js" 75 } 76 } 77 ``` 78 79 ``` js 80 var resolve = require('browser-resolve'); 81 var parent = { filename: __dirname + '/custom/file.js' /*, browser: 'chromeapp' */ }; 82 resolve('./main.js', parent, function(err, path) { 83 console.log(path); 84 }); 85 ``` 86 87 ``` 88 $ node example/custom.js 89 /home/substack/projects/node-browser-resolve/example/custom/custom.js 90 ``` 91 92 ## skip 93 94 You can skip over dependencies by setting a 95 [browser field](https://gist.github.com/defunctzombie/4339901) 96 value to `false`: 97 98 ``` json 99 { 100 "name": "skip", 101 "version": "0.0.0", 102 "browser": { 103 "tar": false 104 } 105 } 106 ``` 107 108 This is handy if you have code like: 109 110 ``` js 111 var tar = require('tar'); 112 113 exports.add = function (a, b) { 114 return a + b; 115 }; 116 117 exports.parse = function () { 118 return tar.Parse(); 119 }; 120 ``` 121 122 so that `require('tar')` will just return `{}` in the browser because you don't 123 intend to support the `.parse()` export in a browser environment. 124 125 ``` js 126 var resolve = require('browser-resolve'); 127 var parent = { filename: __dirname + '/skip/main.js' }; 128 resolve('tar', parent, function(err, path) { 129 console.log(path); 130 }); 131 ``` 132 133 ``` 134 $ node example/skip.js 135 /home/substack/projects/node-browser-resolve/empty.js 136 ``` 137 138 # license 139 140 MIT 141 142 # upgrade notes 143 144 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 resolve. 145 146 This was done to allow package managers to choose which shims they want to use without browser-resolve being the central point of update.