NodeJS: How to Load a Module with require()

We always use the NodeJS require() function to load modules in our projects.
But, how does this actually work?

According to NodeJS documentation, require() is "to require modules." That’s all it says. No kidding.

So I decided to dig deeper, to know what is the magic behind this.

Digging Deeper

All of this happens inside the module.js file.

I investigated by clicking between definitions, and experimenting with variables and properties inside lib/module.js. After a while, the flow of the process became clearer.

When require("path") is called, NodeJS invokes the following modules,

• Module.require()
• Module._load()
• tryModuleLoad
• Module.load()

1. Module.require()

This validates that the path is a string, and that it exists.

// Loads a module at the given file path.
// Returns that module's 'exports' property.
Module.prototype.require = function(path) {
  assert(path, 'missing path');
  assert(typeof path === 'string', 'path must be a string');
  return Module._load(path, this, /*  isMain */ false);
}

This must happen before calling Module._load().

2. Module._load()

This validates that the module exists in the cache. If not, a new instance of Module is created and the module is loaded.

In both cases Module.exports is returned.

3. tryModuleLoad

function tryModuleLoad(module, filename) {
  var threw = true;
  try {
    module.load(filename);
    threw = false;
  } finally {
    if(threw) {
      delete Module._cache[filename];
    }
  }
}

This is just a wrap around module.load() with a try/finally block.

4. Module.load()

In this step, the file is read according to the file’s extension.

For JSON,

// Native extension for .json
Module.extensions['.json'] = function(module, filename) {
  var content = fs.readFileSync(filename, 'utf8');
  try {
    module.exports = JSON.parse(internalModule.stripBOM(content));
  } catch (err) {
    err.message = filename + ': ' + err.message;
    throw err;
  }
};

For Javascript,

// Native extension for .js
Module._extensions['.js'] = function(module, filename) {
  var content = fs.readFileSync(filename, 'utf8');
  module._compile(internalModule.stripDOM(content), filename);
}

FYI, there is also a .node extension reader.

JSON and Javascript

For JSON extensions, the content of the file is parsed and is assigned to the module exports property.

For Javascript, files the function module._compile() is called.

The module creates a wrapper to the code in the file. In turn, the wrapper passes the variables exports, require, and module.

This is why the file can use the module.exports property to export itself. It can also use require() to use other modules.

Module.wrap = function(script) {
  return Module.wrapper[0] + script + Module.wrapper[1];
};

Module.wrapper = [
  '(function (exports, require, module, __filename, __dirname( { ',
  '\n});'
];

Passing the content of the file to the vm to compile and execute the Javascript code,

var compiledWrapper = vm.runInThisContext(wrapper, {
  filename: filename,
  liveOffset: 0,
  displayErrors: true
});

At the end, Module._load returns the module.exports property. All's that left is to return to where require("path") was called.

Finally…

In summary, the basic flow of requiring a module is,
require -> _load -> tryModuleLoad -> load -> process_file

There is a lot more inside module.js, but this is what takes place when require() is called.