install

install is a tiny CommonJS module loader created by Ben Newman that lets you register a nested tree of module factory functions and directories, then require them synchronously - the same way Node does, but without touching the filesystem. It became best known as the runtime powering Meteor’s client-side module system, where synchronous require semantics needed to work inside the browser.

Under the hood, makeInstaller() builds a virtual file tree of File objects representing directories and modules, resolves identifiers using the same relative/absolute/node_modules rules as Node’s own module resolution, and evaluates each module lazily on first require. A fallback option lets missing modules be resolved by another loader (e.g., Node’s native require), and a prefetch/install.fetch API supports asynchronously fetching modules that haven’t been installed yet - useful for streaming code to the browser on demand.

What You Get

• A makeInstaller(options) factory for creating isolated module registries, so multiple independent module trees can coexist without polluting global state.
• Node-compatible module resolution - relative paths, absolute paths, node_modules package lookup, package.json main/browser fields, and index.js fallback - reimplemented without touching the real filesystem.
• A fallback hook so unresolved identifiers can be handed off to another loader (commonly Node’s native require) instead of throwing.
• An async module.prefetch/install.fetch API for lazily fetching and installing modules that weren’t part of the original tree, useful for on-demand code delivery in the browser.

Common Use Cases

• Bundler runtime output - bundlers can compile a whole dependency graph into the nested-object format install() expects and ship this file as the tiny runtime that stitches modules together in the browser.
• Meteor-style synchronous browser modules - apps that need Node’s synchronous require semantics to work client-side without a full async module loader.
• Sandboxed/dynamic module trees - testing or plugin systems that need to construct an isolated require scope from an in-memory tree of factory functions rather than real files on disk.
• Incremental/on-demand loading - combining prefetch with a custom install.fetch implementation to stream additional modules to a running application only when they’re actually required.

Under The Hood

Architecture Read install.js: the File constructor represents either a directory or a module in a virtual tree; fileMergeContents recursively merges nested objects/arrays/functions into that tree; fileResolve implements Node-style identifier resolution (relative, absolute, and node_modules walk-up, with package.json main/browser field and index.js fallback, guarded against re-visiting the same directory via a seenDirFiles list); fileEvaluate lazily invokes a module’s factory function with (require, exports, module) and caches the result on module.exports. All state - the filesByModuleId cache, the root File, defaultExtensions, fallback, mainFields - lives in closures inside makeInstaller(options), so each call produces a fully isolated registry. The whole implementation is one ~550-line file with no submodules, so changes to the core File/Module abstractions have repo-wide blast radius, since every other function is built directly on top of them. It is compact and single-responsibility but tightly coupled through closures over shared mutable state (filesByModuleId, missing, lastPrefetchPromise) rather than explicit dependency injection.

Tech Stack package.json shows plain vanilla JavaScript with no TypeScript and no build step for the library itself - main points straight at install.js, which ships as-is. devDependencies are mocha for the test suite, docco for generating API docs (scripts/docs.sh runs docco against install.js into docs/index.html), reify (the author’s own ES module interop library) to enable import/export syntax inside tests only, and terser to produce a minified install.min.js at publish time (scripts/prepublish.sh). CI is a .travis.yml matrix running Node 4 through 12, reflecting the project’s 2013-2019 active period.

Code Quality test/run.js is a single 1173-line mocha spec covering relative/absolute/node_modules resolution edge cases, package.json main/browser field handling, dynamic prefetch, and fallback behavior - broad coverage relative to the ~550-line source, though concentrated in one file rather than split by concern. There is no TypeScript or type checking anywhere in the codebase. Error handling is explicit: makeMissingError() builds descriptive Cannot find module errors, and the fallback mechanism gives callers an escape hatch rather than silently swallowing failures. Naming is consistent throughout (fileXxx/moduleXxx prefixes tie helper functions to the object type they operate on). There is no linter configuration and no lint/type-check step in CI, which just runs npm test.

What Makes It Unique The specific technical trick is resolving and evaluating an in-memory tree of module factory functions using the same identifier-resolution algorithm Node uses for the real filesystem - relative/absolute paths, extensions, node_modules walk-up, package.json main/browser fields, index.js fallback - without ever touching disk. That is what let Meteor give browser bundles synchronous, Node-compatible require() semantics years before bundler-level dynamic import() became commonplace. The prefetch/install.fetch hook for asynchronously fetching modules not present in the original tree is a distinctive, comparatively early take on on-demand code delivery. It is not novel in a research sense - module loaders are a well-trodden problem - but faithfully emulating Node resolution in a virtual filesystem inside one small, dependency-free file is a focused, clever piece of engineering for its era.