From d34343f0de4c85077dcb1cb15c5e5ea6ad4d9fc6 Mon Sep 17 00:00:00 2001 From: Matt Harrison Date: Wed, 27 Apr 2016 23:41:41 +0100 Subject: [PATCH] doc: mention existence/purpose of module wrapper Included a block in the modules.md file to explain the existence and purpose of the module wrapper. PR-URL: https://github.com/nodejs/node/pull/6433 Reviewed-By: Colin Ihrig Reviewed-By: Evan Lucas Reviewed-By: James M Snell --- doc/api/modules.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 20c8b175cd9340..836285b26f491d 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -30,8 +30,9 @@ The module `circle.js` has exported the functions `area()` and `circumference()`. To add functions and objects to the root of your module, you can add them to the special `exports` object. -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`. +Variables local to the module will be private, because the module is wrapped +in a function by Node.js (see [module wrapper](#modules_the_module_wrapper)). +In this example, the variable `PI` is private to `circle.js`. 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 @@ -425,6 +426,30 @@ These are mostly for historic reasons. **You are highly encouraged to place your dependencies locally in `node_modules` folders.** They will be loaded faster, and more reliably. +## The module wrapper + + + +Before a module's code is executed, Node.js will wrap it with a function +wrapper that looks like the following: + +```js +(function (exports, require, module, __filename, __dirname) { +// Your module code actually lives in here +}); +``` + +By doing this, Node.js achieves a few things: + +- It keeps top-level variables (defined with `var`, `const` or `let`) scoped to +the module rather than the global object. +- It helps to provide some global-looking variables that are actually specific +to the module, such as: + - The `module` and `exports` objects that the implementor can use to export + values from the module. + - The convenience variables `__filename` and `__dirname`, containing the + module's absolute filename and directory path. + ## The `module` Object