Where Does Node.js And Require() Look For Modules?

In the last week or so, I've started to experiment with building server-side Javascript code for Node.js. When you build a Node.js application, you can use the global require() method to load and cache Javascript modules. These modules provide localized memory spaces that can house singletons and class definitions. When you invoke the require() method, Node.js searches a number of system paths looking for the module in question. This morning, I was brought to the edge of sanity trying to figure out what that searching algorithm was. After failing to find anything useful in the Node.js docs regarding the require() method, Jeremy Martin came to my rescue, pointing me to the documentation on Modules.

If you want to load a local, relative Javascript module into a Node.js application, you can simply use the require() method in conjunction with relative (or absolute) file paths:

NOTE: The (.js) file extension is optional. Node.js will add it for you when attempting to load the file. It will also attempt to load the given module as a directory with an index file (index.js) or a package description (package.json).

Ok, so that stuff makes sense - relative file paths are something that I can wrap my head around. But what about when no file path is used? Where does Node.js look if you attempt to include a module by name alone:

This is where I really started to lose my sanity this morning! When you refer to a Node.js module by name, Node.js uses a complex searching algorithm to locate the requested source code.

First, Node.js looks to see if the given module is a core module - Node.js comes with many modules compiled directly into the executable binary (ex. http, fs, sys, events, path, etc.). These core modules will always take precedence in the loading algorithm.

If the given module is not a core module, Node.js will then begin to search for a directory named, "node_modules". It will start in the current directory (relative to the currently-executing Javascript file in Node) and then work its way up the folder hierarchy, checking each level for a node_modules folder.

Once Node.js finds the node_modules folder, it will then attempt to load the given module either as a (.js) Javascript file or as a named sub-directory. And, if it finds the named sub-directory, it will then attempt to load the file in various ways. So, for example, if you make a request to load the module, "utils":

... Node.js will perform a hierarchical directory search for "node_modules" and "utils" in the following ways:

• ./node_modules/utils.js
• ./node_modules/utils/index.js
• ./node_modules/utils/package.json

If it still can't find the file in this directory-spidering manner, Node.js will then proceed to look at the directory paths outlined in the "require.paths" array. The paths values in this array default to the paths defined, in part, by the environmental variable, NODE_PATH; but, they can be updated programmatically within a Node.js application.

NOTE: From what I have read, programmatically updating the "require.paths" value is considered bad practice.

If I log my default require.paths value to the console, here is what I get:

[
'/usr/local/lib/node',
'/Users/ben/.node_modules',
'/Users/ben/.node_libraries',
'/usr/local/Cellar/node/0.4.5/lib/node'
]

I write all of this in an attempt to hammer this Node.js module search overview into my head. If you want to know more about Node.js's module search algorithm, check out the documentation on Modules. There, you can find a much more in-depth explanation of the search algorithm including module path caching and package descriptions.

Ok - now I can start to breathe a bit easier. I'm serious - I almost lost it a few times trying to get to the bottom of this.

You Might Also Be Interested In: