node/doc/api/modules.markdown

Standard Modules

Node comes with a number of modules that are compiled in to the process, most of which are documented below. The most common way to use these modules is with require('name') and then assigning the return value to a local variable with the same name as the module.

Example:

var util = require('util');

It is possible to extend node with other modules. See 'Modules'

Modules

Node uses the CommonJS module system.

Node has a simple module loading system. In Node, files and modules are in one-to-one correspondence. As an example, foo.js loads the module circle.js in the same directory.

The contents of foo.js:

var circle = require('./circle');
console.log( 'The area of a circle of radius 4 is '
           + circle.area(4));

The contents of circle.js:

var PI = 3.14;

exports.area = function (r) {
  return PI * r * r;
};

exports.circumference = function (r) {
  return 2 * PI * r;
};

The module circle.js has exported the functions area() and circumference(). To export an object, add to the special exports object. (Alternatively, one can use this instead of exports.) Variables local to the module will be private. In this example the variable PI is private to circle.js. The function puts() comes from the module 'util', which is a built-in module. Modules which are not prefixed by './' are built-in modules--more about this later.

Module Resolving

A module prefixed with './' is relative to the file calling require(). That is, circle.js must be in the same directory as foo.js for require('./circle') to find it.

Without the leading './', like require('assert') the module is searched for in the require.paths array. require.paths on my system looks like this:

[ '/home/ryan/.node_modules' ]

That is, when require('foo') is called Node looks for:

• 1: /home/ryan/.node_modules/foo
• 2: /home/ryan/.node_modules/foo.js
• 3: /home/ryan/.node_modules/foo.node
• 4: /home/ryan/.node_modules/foo/index.js
• 5: /home/ryan/.node_modules/foo/index.node

interrupting once a file is found. Files ending in '.node' are binary Addon Modules; see 'Addons' below. 'index.js' allows one to package a module as a directory.

require.paths can be modified at runtime by simply unshifting new paths onto it, or at startup with the NODE_PATH environmental variable (which should be a list of paths, colon separated). Additionally node will search for directories called node_modules starting at the current directory (of the module calling require) and upwards towards the root of the package tree. This feature makes it easy to have different module versions for different environments. Imagine the situation where you have a development environment and a production environment each with a different version of the foo module: projects/x/development/node_modules/foo and projects/x/production/node_modules/foo.

The second time require('foo') is called, it is not loaded again from disk. It looks in the require.cache object to see if it has been loaded before.

To get the exact filename that will be loaded when require() is called, use the require.resolve() function.