Loading from Folders
If the module identifier passed to is not a core module, and does not begin with or then Node.js starts at the parent directory of the current module, and adds, and attempts to load the module from that location.
Node will not append to a path already ending in
If it is not found there, then it moves to the parent directory, and so on, until the root of the file system is reached.
For example, if the file at called, then Node.js would look in the following locations, in this order:
This allows programs to localize their dependencies, so that they do not clash.
It is possible to require specific files or sub modules distributed with a module by including a path suffix after the module name.
For instance would resolve relative to where is located.
The suffixed path follows the same module resolution semantics.
Loading from the global folders
If the environment variable is set to a colon-delimited list of absolute paths, then Node.js will search those paths for modules if they are not found elsewhere.
On Windows, is delimited by semicolons instead of colons.
was originally created to support loading modules from varying paths before the current module resolution algorithm was frozen.
is still supported, but is less necessary now that the Node.js ecosystem has settled on a convention for locating dependent modules.
Sometimes deployments that rely on show surprising behavior when people are unaware that must be set. Sometimes a module's dependencies change, causing a different version (or even a different module) to be loaded as the is searched.
Additionally, Node.js will search in the following locations:
Where is the user's home directory, and is Node.js's configured
These are mostly for historic reasons.
It is strongly encouraged to place dependencies in the local folder.
These 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:
Module code actually lives in here
By doing this, Node.js achieves a few things:
It keeps top-level variables (defined with or) 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 and objects that the implementor can use to export values from the module.
The convenience variables and, containing the module's absolute filename and directory path.
The module scope
The directory name of the current module.
This is the same as the of the
Example: running from
The file name of the current module. This is the resolved absolute path of the current module file.
For a main program this is not necessarily the same as the file name used in the command line.
See for the directory name of the current module.
Given two modules: and, where is a dependency of and there is a directory structure of:
References to within will return while references to within will return
A reference to the that is shorter to type.
See the section about the exports shortcut for details on when to use and when to use
A reference to the current module, see the section about the
In particular, is used for defining what a module exports and makes available through
To require modules.
Modules are cached in this object when they are required. By deleting a key value from this object, the next will reload the module. Note that this does not apply to native addons, for which reloading will result in an error.
Stability: 0 - Deprecated
Instruct on how to handle certain file extensions.
Process files with the extension as
Since the module system is locked, this feature will probably never go away. However, it may have subtle bugs and complexities that are best left untouched.
Note that the number of file system operations that the module system has to perform in order to resolve a statement to a filename scales linearly with the number of registered extensions.
In other words, adding extensions slows down the module loader and should be discouraged.
The object representing the entry script loaded when the Node.js process launched.
The module path to resolve.
Paths to resolve module location from.
If present, these paths are used instead of the default resolution paths. Note that each of these paths is used as a starting point for the module resolution algorithm, meaning that the hierarchy is checked from this location.
Use the internal machinery to look up the location of a module, but rather than loading the module, just return the resolved filename.
The module path whose lookup paths are being retrieved.
Returns an array containing the paths searched during resolution of or if the string references a core module, for example or
In each module, the free variable is a reference to the object representing the current module
For convenience, is also accessible via the module-global.
is not actually a global but rather local to each module.
The module objects required by this one.
The object is created by the 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. Note that assigning the desired object to will simply rebind the local variable, which is probably not what is desired.
For example suppose we were making a module called
Do some work, and after some time emit the event from the module itself.
Then in another file we could do:
Note that assignment to must be done immediately. It cannot be done in any callbacks. This does not work:
The variable is available within a module's file-level scope, and is assigned the value of before the module is evaluated.
It allows a shortcut, so that can be written more succinctly as. However, be aware that like any variable, if a new value is assigned to, it is no longer bound to
Exported from require of module
Not exported, only available in the module
When the property is being completely replaced by a new object, it is common to also reassign
To illustrate the behavior, imagine this hypothetical implementation of which is quite similar to what is actually done by
Module code here. In this example, define a function.
At this point, is no longer a shortcut to, and this module will still export an empty default object.
At this point, the module will now export, instead of the default object.
The fully resolved filename to the module.
The identifier for the module. Typically this is the fully resolved filename
Whether or not the module is done loading, or is in the process of loading.
The module that first required this one.
The search paths for the module.
Returns: from the resolved module
The method provides a way to load a module as if was called from the original module.
In order to do this, it is necessary to get a reference to the object. Since returns the, and the is typically only available within a specific module's code, it must be explicitly exported in order to be used.
Provides general utility methods when interacting with instances of — the variable often seen in file modules. Accessed via
A list of the names of all modules provided by Node.js. Can be used to verify if a module is maintained by a third party or not.
Note that in this context isn't the same object that's provided by the module wrapper. To access it, require the module: