Skip to content

Latest commit

 

History

History
116 lines (84 loc) · 3.98 KB

modules.markdown

File metadata and controls

116 lines (84 loc) · 3.98 KB
Raw

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.

Any folders named "node_modules" that exist in the current module path will also be appended to the effective require path. This allows for bundling libraries and other dependencies in a 'node_modules' folder at the root of a program.

To avoid overly long lookup paths in the case of nested packages, the following 2 optimizations are made:

  1. If the module calling require() is already within a node_modules folder, then the lookup will not go above the top-most node_modules directory.
  2. Node will not append node_modules to a path already ending in node_modules.

So, for example, if the file at /usr/lib/node_modules/foo/node_modules/bar.js were to do require('baz'), then the following places would be searched for a baz module, in this order:

  • 1: /usr/lib/node_modules/foo/node_modules
  • 2: /usr/lib/node_modules

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.