tessl/npm-browser-resolve

Node.js module resolution algorithm with browser field support for handling browser-specific module mappings

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Browser Resolve

Name: tessl/npm-browser-resolve
Author: tessl

Browser Resolve is a Node.js module resolution algorithm with browser field support. It extends the standard Node.js require.resolve() to handle browser-specific module mappings defined in package.json files through the 'browser' field specification, enabling proper module resolution for browser environments.

Package Information

Package Name: browser-resolve
Package Type: npm
Language: JavaScript
Installation: npm install browser-resolve

Core Imports

CommonJS (primary format):

const resolve = require('browser-resolve');

ES modules (when using Node.js with ESM or bundlers):

import resolve from 'browser-resolve';

Basic Usage

const resolve = require('browser-resolve');

// Async resolution
resolve('../some-module', { filename: __filename }, function(err, path) {
    if (err) throw err;
    console.log('Resolved to:', path);
});

// Sync resolution
try {
    const resolvedPath = resolve.sync('../some-module', { filename: __filename });
    console.log('Resolved to:', resolvedPath);
} catch (err) {
    console.error('Resolution failed:', err);
}

// Browser field resolution
resolve('./main.js', { 
    basedir: '/path/to/package',
    browser: 'browser' // use browser field from package.json
}, function(err, path) {
    console.log('Browser-specific path:', path);
});

// Core module shimming
const shims = {
    http: '/path/to/browser-http.js',
    fs: false // exclude fs module
};

resolve('http', { modules: shims }, function(err, path) {
    console.log('Shimmed path:', path);
});

Capabilities

Asynchronous Resolution

Resolves a module path asynchronously with browser field support and calls a callback with the result.

/**
 * Resolve a module path and call cb(err, path [, pkg])
 * @param {string} id - Module identifier to resolve
 * @param {ResolveOptions} opts - Resolution options
 * @param {function} cb - Callback function (err, path, pkg) => void
 */
function resolve(id, opts, cb);

Synchronous Resolution

Resolves a module path synchronously with browser field support and returns the resolved path.

/**
 * Synchronously resolve a module path
 * @param {string} id - Module identifier to resolve  
 * @param {ResolveOptions} opts - Resolution options
 * @returns {string} - Resolved path
 * @throws {Error} - If resolution fails
 */
resolve.sync = function(id, opts);

Configuration Options

All resolution functions accept an options object with the following properties:

interface ResolveOptions {
  /** Directory to begin resolving from */
  basedir?: string;
  
  /** The package.json property to use for browser mappings (defaults to 'browser') */
  browser?: string;
  
  /** The calling filename where require() originated */
  filename?: string;
  
  /** Module id/name -> path mappings for core modules */
  modules?: { [key: string]: string | false };
  
  /** Transform parsed package.json contents before looking at main field */
  packageFilter?: (pkg: any, pkgdir: string) => any;
  
  /** require.paths array for additional search paths */
  paths?: string[];
  
  /** Filter resolved paths during resolution */
  pathFilter?: (pkg: any, path: string, relativePath: string) => string;
}

Browser Field Support

The library supports various browser field formats in package.json:

String Replacement

{
  "main": "index.js",
  "browser": "browser.js"
}

Object Mappings

{
  "browser": {
    "./server.js": "./client.js",
    "./lib/fs.js": false
  }
}

Module Exclusion

{
  "browser": {
    "fs": false,
    "crypto": false
  }
}

Custom Browser Field Names

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

// Use custom browser field
resolve('./main.js', { browser: 'chromeapp' }, callback);

Core Module Handling

Browser Resolve provides flexible core module handling:

// Define custom core module mappings
const modules = {
    'http': '/path/to/browser-http.js',
    'fs': '/path/to/browser-fs.js',
    'crypto': false // exclude crypto module
};

resolve('http', { modules: modules }, function(err, path) {
    // path will be '/path/to/browser-http.js'
});

resolve('crypto', { modules: modules }, function(err, path) {
    // path will be the empty module (exclusion)
});

Module Exclusion

When a browser field maps a module to false, it resolves to an empty module:

// If package.json has: { "browser": { "fs": false } }
resolve('fs', { basedir: '/path/to/package' }, function(err, path) {
    // path will be '/path/to/browser-resolve/empty.js'
});

Error Handling

The library handles various error conditions gracefully:

File System Errors: ENOENT errors are handled during package.json discovery
JSON Parse Errors: Include file path context in error messages
Resolution Failures: Propagated from underlying resolve library
Sync vs Async: Async methods pass errors to callback, sync methods throw directly

// Async error handling
resolve('non-existent-module', opts, function(err, path) {
    if (err) {
        console.error('Resolution failed:', err.message);
        return;
    }
    console.log('Resolved:', path);
});

// Sync error handling
try {
    const path = resolve.sync('non-existent-module', opts);
    console.log('Resolved:', path);
} catch (err) {
    console.error('Resolution failed:', err.message);
}

Package Dependencies

Browser Resolve depends on:

resolve (^1.17.0): Core Node.js resolution algorithm
fs: File system operations (built-in)
path: Path manipulation utilities (built-in)

Legacy Support

The library maintains backward compatibility:

Legacy browserify field: Falls back to browserify field if browser field is not present
Flexible browser field names: Support for custom property names beyond 'browser'
Node.js resolve compatibility: All options from node-resolve are supported

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/browser-resolve@2.0.x
Publish Source: CLI
Badge