Breakdown of How Require Extensions Work

How_Require_Extensions_Work.md

Why

Doing require extensions correctly is essential, because:

1. Users should be able to install multiple extensions in succession, and have them work together.
2. Coverage tools like nyc need it to reliably supply coverage information that takes into account sourcemaps from upstream transforms.
3. Because non-standard, un-predictable behavior causes hard to solve bugs, and major headaches for project maintainers.

What is a require extension anyways?

First, it's worth remembering what default ".js" extension does.

require.extenstions['.js'] = function (module, filename) {
  var content = fs.readFileSync(filename, 'utf8');
  module._compile(internalModule.stripBOM(content), filename);
}

Really simple. It reads the source content from the disk, and calls the module._compile. The default module._compile is a non-trivial piece of code, for simplicity I will just say it is what actually compiles the code.

---

Our first custom extension

Now let's install a transform that just appends the code + "bar" to the end of every file (humor me as I keep things simple).

This is how you would manually create that hook (in what is now widely accepted as the "right" way).

// append-bar.js
var oldHoook = require.extensions['.js'];                 // 1
require.extensions['.js'] = function (module, file) {     // 2
  var oldCompile = module._compile;                       // 3
  module._compile = function (code, file) {               // 4
    code = code + ' + "bar"';                             // 5            
    module._compile = oldCompile;                         // 6
    module._compile(code + ' + "bar"');                   // 7
  };
  oldHook(module, file);                                  // 9
});

Note that this extension never reads from the disk. That is because the first extension in the chain (the system default one) handles loading from disk. If it's not obvious why that's true (it wasn't for me), keep reading.

The really important takeaway here is that you should be implementing require extensions almost exactly as I have above. There are multiple levels of indirection, and it can be confusing. Libraries like pirates can simplify the process.

Breakdown with 1 Custom Extension

Here is what happens when you call require("./foo.js")

// foo.js
module.exports = "foo"

What happens inside require boils down to this:

function pseudoRequire(filename) {
  var ext = path.extname(filename); // ".js"
  var module = new Module();
  require.extensions[ext](module, filename);
}

Now let's step through the sequence of events.

1. The system calls require.extensions['.js'](module, './foo.js').
   This means append-bar is invoked with (module, './foo.js')
2. append-bar stores a reference to module._compile (line 3), an with its own wrapper function (line 4).
   module._compile refers to the append-bar wrapper function. append-bar's reference to originalCompile refers to the actual compile implementation.
3. append-bar calls it's oldHook (the default .js extension) with the modified module and filename (line 9).
4. The default .js extension reads in the source (module.exports = "foo"), and calls module._compile(source, filename). Remember module._compile currently points to the append-bar wrapper function.
5. The append-bar wrapper adds + "bar" to the source (Line 5). The source is now module.exports = "foo" + "bar".
6. The append-bar wrapper now replaces module._compile with it's originalCompile reference (Line 6). module._compile now points to the actual compile implementation
7. module._compile is called again (this time pointing to actual, and the source is evaled and we get our result "foobar".

Breakdown with 2 Custom Extension

Assume we have first added the append-bar extension from above, followed by another called append-quz (which is for all purposes identical, except it appends baz instead.

1. We install the append-bar extension (replacing the original hook) append-bar#originalHook points to the original hook.
2. We install the append-quz extension append-quz#originalHook points to the append-bar hook.
3. We call require('./foo.js');
4. append-quz hook is called with (module, './foo.js'), it replaces module._compile with it's wrapper function. append-quz#originalCompile points to the actual compile module._compile points to the append-quz wrapper.
5. append-quz calls it's originalHook reference, which is append-bar.
6. append-bar replaces module._compile with it's wrapper. append-bar#originalCompile points to append-quz wrapper. module._compile points to the append-bar wrapper.
7. The original extension is called, which loads the source from disk and calls module._compile('module.exports = "foo"', './foo.js')
8. At this point module._compile points to the append-bar wrapper, so the source is appended with + "bar".
9. The append-bar calls the originalCompile reference (which is the append-quz wrapper).
10. The append-quz wrapper does it's appending (so we've now got "foo" + "bar" + "quz")
11. append-quz calls it's originalCompile reference, which is actual and we get "foobarquz"