browser-resolve

What is browser-resolve?

The browser-resolve npm package is designed to resolve module dependencies in a way that is compatible with how browsers resolve modules, as opposed to the Node.js resolution algorithm. This is particularly useful for bundling packages for use in the browser where the Node.js module resolution strategy (e.g., handling of the 'main' field in package.json) does not apply.

What are browser-resolve's main functionalities?

Resolving browser-specific module entry points

This feature allows developers to resolve the path to a module's browser-specific entry point, if specified in the module's package.json, instead of the Node.js entry point. This is useful for bundling modules for the browser.

var resolve = require('browser-resolve');
resolve('module-name', { filename: '/path/to/file.js' }, function (err, res) {
  if (err) console.log(err);
  console.log(res);
});

Other packages similar to browser-resolve

resolve

Similar to browser-resolve, the 'resolve' package is a module resolution library for Node.js, mimicking Node's require/resolution mechanism. The key difference is that 'resolve' focuses on Node.js environments, while 'browser-resolve' targets browser environments, taking into account browser-specific fields in package.json.

webpack

Webpack is a powerful module bundler that can resolve dependencies and modules for browser environments. Unlike browser-resolve, which is a simple resolution library, webpack offers a wide range of features including bundling, minification, and plugin support. Webpack's resolution mechanism is more complex and configurable, designed for comprehensive build processes.

browserify

Browserify is a tool that allows developers to use Node.js-style modules in the browser. It resolves dependencies and bundles modules together. While browser-resolve provides the resolution logic similar to what Browserify uses under the hood, Browserify offers a complete bundling solution, transforming Node.js modules so they can run in the browser.

README

browser-resolve

node.js resolve algorithm with browser field support.

api

bresolve(id, opts={}, cb)

Resolve a module path and call cb(err, path [, pkg])

Options:

• basedir - directory to begin resolving from
• browser - the 'browser' property to use from package.json (defaults to 'browser')
• filename - the calling filename where the require() call originated (in the source)
• modules - object with module id/name -> path mappings to consult before doing manual resolution (use to provide core modules)
• packageFilter - transform the parsed package.json contents before looking at the main field
• paths - require.paths array to use if nothing is found on the normal node_modules recursive walk

Additionally, options supported by node-resolve can be used.

bresolve.sync(id, opts={})

Same as the async resolve, just uses sync methods.

Additionally, options supported by node-resolve can be used.

basic usage

you can resolve files like require.resolve():

var bresolve = require('browser-resolve');
bresolve('../', { filename: __filename }, function(err, path) {
    console.log(path);
});

$ node example/resolve.js
/home/substack/projects/browser-resolve/index.js

core modules

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.

var shims = {
    http: '/your/path/to/http.js'
};

var bresolve = require('browser-resolve');
bresolve('http', { modules: shims }, function(err, path) {
    console.log(path);
});

$ node example/builtin.js
/home/substack/projects/browser-resolve/builtin/http.js

browser field

browser-specific versions of modules

{
  "name": "custom",
  "version": "0.0.0",
  "browser": {
    "./main.js": "custom.js"
  }
}

var bresolve = require('browser-resolve');
var parent = { filename: __dirname + '/custom/file.js' };
bresolve('./main.js', parent, function(err, path) {
    console.log(path);
});

$ node example/custom.js
/home/substack/projects/browser-resolve/example/custom/custom.js

You can use different package.json properties for the resolution, if you want to allow packages to target different environments for example:

{
  "browser": { "./main.js": "custom.js" },
  "chromeapp": { "./main.js": "custom-chromeapp.js" }
}

var bresolve = require('browser-resolve');
var parent = { filename: __dirname + '/custom/file.js', browser: 'chromeapp' };
bresolve('./main.js', parent, function(err, path) {
    console.log(path);
});

$ node example/custom.js
/home/substack/projects/browser-resolve/example/custom/custom-chromeapp.js

skip

You can skip over dependencies by setting a browser field value to false:

{
  "name": "skip",
  "version": "0.0.0",
  "browser": {
    "tar": false
  }
}

This is handy if you have code like:

var tar = require('tar');

exports.add = function (a, b) {
    return a + b;
};

exports.parse = function () {
    return tar.Parse();
};

so that require('tar') will just return {} in the browser because you don't intend to support the .parse() export in a browser environment.

var bresolve = require('browser-resolve');
var parent = { filename: __dirname + '/skip/main.js' };
bresolve('tar', parent, function(err, path) {
    console.log(path);
});

$ node example/skip.js
/home/substack/projects/browser-resolve/empty.js

license

MIT

upgrade notes

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().

This was done to allow package managers to choose which shims they want to use without browser-resolve being the central point of update.

Changelog

2.0.0 - 2020-08-03

• Update resolve to 1.17.0+.

Technically, this is a bugfix and feature update. However, older browserify versions rely on a resolve bug, and would break if this was published as a minor version update.