nodejs/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.

Additionally, a `package.json` file may be used to treat a folder as a
module, if it specifies a `'main'` field.  For example, if the file at
`./foo/bar/package.json` contained this data:

    { "name" : "bar",
      "version" : "1.2.3",
      "main" : "./lib/bar.js" }

then `require('./foo/bar')` would load the file at
`'./foo/bar/lib/bar.js'`.  This allows package authors to specify an
entry point to their module, while structuring their package how it
suits them.

`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).


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.