From 5ac6f4de13bb2f18c264dfccfdcfea5a9118d43e Mon Sep 17 00:00:00 2001 From: Ryan Graham Date: Fri, 25 Oct 2013 22:03:02 -0700 Subject: [PATCH] doc: improve module documentation Expands on when to use module.exports vs. exports. This is a recurring question on mailing list and continues to confuse new devs. --- doc/api/globals.markdown | 8 +++-- doc/api/modules.markdown | 78 ++++++++++++++++++++++++++++------------ 2 files changed, 60 insertions(+), 26 deletions(-) diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown index cd6a33d3a8f..4fb86133823 100644 --- a/doc/api/globals.markdown +++ b/doc/api/globals.markdown @@ -124,7 +124,9 @@ Example: running `node example.js` from `/Users/mjr` * {Object} A reference to the current module. In particular -`module.exports` is the same as the `exports` object. +`module.exports` is used for defining what a module exports and makes +available through `require()`. + `module` isn't actually a global but rather local to each module. See the [module system documentation][] for more information. @@ -133,10 +135,10 @@ See the [module system documentation][] for more information. -A reference to the `module.exports` object which is shared between all -instances of the current module and made accessible through `require()`. +A reference to the `module.exports` that is shorter to type. See [module system documentation][] for details on when to use `exports` and when to use `module.exports`. + `exports` isn't actually a global but rather local to each module. See the [module system documentation][] for more information. diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index c551cb01083..a9c503448e8 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -27,27 +27,34 @@ The contents of `circle.js`: }; The module `circle.js` has exported the functions `area()` and -`circumference()`. To export an object, add to the special `exports` -object. +`circumference()`. To add functions and objects to the root of your module, +you can add them to the special `exports` object. -Note that `exports` is a reference to `module.exports` making it suitable -for augmentation only. If you are exporting a single item such as a -constructor you will want to use `module.exports` directly instead. +Variables local to the module will be private, as though the module was wrapped +in a function. In this example the variable `PI` is private to `circle.js`. - function MyConstructor (opts) { - //... +If you want the root of your module's export to be a function (such as a +constructor) or if you want to export a complete object in one assignment +instead of building it one property at a time, assign it to `module.exports` +instead of `exports`. + +Below, `bar.js` makes use of the `square` module, which exports a constructor: + + var square = require('./square.js'); + var mySquare = square(2); + console.log('The area of my square is ' + mySquare.area()); + +The `square` module is defined in `square.js`: + + // assigning to exports will not modify module, must use module.exports + module.exports = function(width) { + return { + area: function() { + return width * width; + } + }; } - // BROKEN: Does not modify exports - exports = MyConstructor; - - // exports the constructor properly - module.exports = MyConstructor; - -Variables -local to the module will be private. In this example the variable `PI` is -private to `circle.js`. - The module system is implemented in the `require("module")` module. ## Cycles @@ -232,18 +239,21 @@ would resolve to different files. * {Object} In each module, the `module` free variable is a reference to the object -representing the current module. In particular -`module.exports` is accessible via the `exports` module-global. -`module` isn't actually a global but rather local to each module. +representing the current module. For convenience, `module.exports` is +also accessible via the `exports` module-global. `module` isn't actually +a global but rather local to each module. ### module.exports * {Object} The `module.exports` object is created by the Module system. Sometimes this is not -acceptable, many want their module to be an instance of some class. To do this -assign the desired export object to `module.exports`. For example suppose we -were making a module called `a.js` +acceptable; many want their module to be an instance of some class. To do this +assign the desired export object to `module.exports`. Note that assigning the +desired object to `exports` will simply rebind the local `exports` variable, +which is probably not what you want to do. + +For example suppose we were making a module called `a.js` var EventEmitter = require('events').EventEmitter; @@ -277,6 +287,28 @@ y.js: var x = require('./x'); console.log(x.a); +#### exports alias + +The `exports` variable that is available within a module starts as a reference +to `module.exports`. As with any variable, if you assign a new value to it, it +is no longer bound to the previous value. + +To illustrate the behaviour, imagine this hypothetical implementation of +`require()`: + + function require(...) { + // ... + function (module, exports) { + // Your module code here + exports = some_func; // re-assigns exports, exports is no longer + // a shortcut, and nothing is exported. + module.exports = some_func; // makes your module export 0 + } (module, module.exports); + return module; + } + +As a guideline, if the relationship between `exports` and `module.exports` +seems like magic to you, ignore `exports` and only use `module.exports`. ### module.require(id)