Install.js CommonJS Module Loader for Browsers

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require` in a browser environment without `install.js` being loaded and initialized, or before the `makeInstaller` and `install` steps have provided a local `require` function. CommonJS `require` is not native to browsers.
  fix Ensure `install.js` (or a bundled version) is correctly loaded in your HTML, and that `makeInstaller` and the subsequent `install` calls have been executed to create the `require` function for your modules.

• Error: Cannot find module 'some-module'

  cause This error occurs when the `install` loader cannot resolve a module identifier. This could be due to an incorrect path, the module not being explicitly 'installed' via the `install` function's object tree, or misconfiguration of `extensions` or `mainFields` in `makeInstaller`.
  fix Verify the module identifier path is correct relative to the calling module. Ensure the module is present in the object tree passed to `install`. Check `makeInstaller` options, especially `extensions` for implicit file endings and `mainFields` for `package.json` resolution.

• module.exports = ... or exports.property = ... is not working as expected with `import` statements.

  cause The `install` package implements a CommonJS-like module system. While it uses `exports` and `module.exports`, these are not directly compatible with native ECMAScript `import` statements without an intermediate bundling or transpilation step.
  fix This package is designed for CommonJS. If you are in an ESM context, you would typically use a bundler (like Webpack) that understands both CJS and ESM to integrate modules handled by `install`. If sticking to `install`, use `require()` within its defined module contexts.

Warnings

• breaking The package's primary purpose—loading CommonJS modules directly in browsers—has been largely superseded by modern JavaScript bundlers (Webpack, Rollup, Parcel) and native ECMAScript Modules (ESM). Using `install` in new projects may introduce unnecessary complexity or reliance on an older module paradigm.
  Fix: For new projects, consider modern bundlers for CommonJS/ESM compatibility or use native ESM. For legacy CommonJS in browsers, evaluate if a bundler could simplify the build process.
• gotcha In a Node.js environment, the `install` package creates its own `require` context. Directly assigning the result of `install()` to a global `require` variable (e.g., `require = install(...)`) can overwrite Node.js's native `require` function, leading to unexpected behavior or breakage for built-in modules.
  Fix: Always assign the result of `install()` to a locally scoped variable (e.g., `const myRequire = install(...)`) to avoid conflicts with Node.js's native module system.
• gotcha The package has not seen updates since 2018 (version 0.13.0). This indicates it is no longer actively maintained. Relying on it for critical applications might pose long-term maintenance or security risks, as it may not receive updates for new JavaScript features, bug fixes, or security vulnerabilities.
  Fix: Assess the necessity of this package. If possible, migrate to actively maintained alternatives or modern bundling solutions that are compatible with CommonJS for long-term project health.

Install

• npm install install npm
• yarn add install yarn
• pnpm add install pnpm

Imports

• makeInstaller
  wrong:

  import { makeInstaller } from 'install';

  correct:

  const install = require('install').makeInstaller;

  This package is CommonJS-first. ESM `import` syntax is not directly supported without a transpiler or bundler.
• install
  wrong:

  const installFn = require('install');

  correct:

  const installFn = require('install').makeInstaller({...});

  The primary `install` function is the *return value* of `makeInstaller`, not directly exported by the package.
• require (from installed modules)
  wrong:

  require('./my-module');

  correct:

  const localRequire = installFn({...}); localRequire('./my-module');

  The `require` function within installed modules is local to the `install` function's context, not the global Node.js `require` or browser global. Be careful not to overwrite the global `require` in Node.js.

Quickstart

This quickstart demonstrates how to initialize the `install` module loader, define and install custom CommonJS modules, and then `require` them using the loader's context. It shows the three main steps: `makeInstaller`, `install`, and `require`.

const makeInstaller = require('install').makeInstaller;

// Step 1: Create an install function with optional configurations
const install = makeInstaller({
  extensions: [".js", ".json"],
  // fallback: (id) => { /* custom resolution logic, e.g., native Node.js require */ },
  browser: typeof window !== 'undefined',
  mainFields: ["browser", "main"]
});

// Step 2: Install modules using a nested object tree
const localRequire = install({
  "main.js"(require, exports, module) {
    const assert = require("assert"); // Example: requiring a module within the installed context

    assert.strictEqual(
      require("package").name,
      "/node_modules/package/entry.js"
    );

    exports.name = module.id;
  },

  node_modules: {
    package: {
      "package.json"(require, exports, module) {
        exports.name = "package";
        exports.version = "0.1.0";
        exports.main = "entry.js";
      },
      "entry.js"(require, exports, module) {
        exports.name = module.id;
      }
    }
  }
});

// Step 3: Require the entry point module(s) to evaluate them
console.log(localRequire("./main").name);
// Expected output: "/main.js"