Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

This package has been deprecated

Author message:

To support es6 modules, use 'module-walker' instead.


8.0.0 • Public • Published

NPM version Build Status


Analyzes and walks down the dependencies from a commonjs entry and creates a walking tree.

var walker = require('commonjs-walker');

NOTICE that it will not walk down node_modules and any foreign packages.


  • require() a directory.
  • If a module is not found, commonjs-walker will attempt to load the required filename with the added extension of .js, .json, and then .node, according to File Modules
  • You can define what extensions should commonjs-walker fallback to by options.extensions, which will be very usefull for browser-side commonjs modules.


  // walk down another entry
  // walk down many entries
  .walk(['/path/to/entry3.js', '/path/to/entry4.js'])
  .done(function(err, nodes){
   // ...

Returns an EventEmitter.

Walks down from a entry point, such as package.main of commonjs or any JavaScript file based on CommonJS, and tries to create a walker.Module instance of the top level.

  • entry Path the absolute path of the entry point.
  • nodes Object the hashmap of <path>: <walker.Module>

If the file structure of your project is (actually it is a very extreme scenario):

       |-- index.js
       |-- a.png
       |-- a
           |-- index.json


var image = require.resolve('./a.png')




walker().walk('/path/to/index.js').done(function(err, nodes){

Then, the nodes object will be something like:

  '/path/to/index.js': {
    require: {
      './a': '/path/to/a/index.json',
      'b': 'b'
    resolve: {
      './a.png': '/path/to/a.png'
    content: <buffer>
  '/path/to/a.png': {
    require: {}
  '/path/to/a/index.json': {
    require: {},
    content: <buffer>
  'b': {
    foreign: true


All options are optional. By default, walker works in a very strict mode.

Option Type Default Description
allow_cyclic Boolean true whether should check cyclic dependencies
check_require_length Boolean false whether should check the arguments.length of method require()
allow_non_literal_require Boolean true whether should check the usage of method require(). If false, the argument of require() must be an literal string.
comment_require Boolean true whether should parse @require(), @require.resolve and @require.async in comments.
require_resolve Boolean true whether should analysis the usage of require.resolve().
require_async Boolean true whether should record the usage of require.async().
allow_absolute_path Boolean true whether should allow to require an absolute path.
extensions Array ['.js', '.json', '.node'] see options.extensions section


type Array

When we require() a path, if path is not found, nodejs will attempt to load the required filename with the added extension of .js, .json, and then .node. Reference via

But for browser-side environment, most usually, we do not support extension .node which is what options.extensions is for.

Especially, only tree values below are allowed:

  • ['.js']
  • ['.js', '.json'],
  • ['.js', '.json', '.node']

Frequent Options for Browsers

  allow_cyclic: false,
  strict_require: true,
  allow_absolute_path: false,
  extensions: ['.js', '.json']



Register compilers to precompile a file

  • compiler
    • compiler.test RegExp|String to match the given path
    • compiler.compiler function(content, options, callback)
      • callback function(err, result)
        • err Error=null
        • result.content String the compiled content.
        • result.js Boolean=false to indicate that if the compiled content is an javascript file.
        • result.json Boolean=false to indicate that if the compiled content is a json file.


Event: warn

  • message String

Emits if there is a warning. Warnings are potential problems that might break your code, including:

  • cyclic dependencies
  • require an absolute path

Struct: walker.Module

Actually, there is no walker.Module exists. We only use it to declare and describe the structure of the module.

For All types

Property Type Description
foreign Boolean whether the current module is from a foreign package.
require Object The <id>: <path> map. id is the module identifier user require()d in the module file.
resolve Object
async Object

Class: walker.Error

  • code String the enum type of the error
  • message String error messages
  • stack String the origin error.stack
  • data Object the object of the major information of the error, this is useful for i18n.

Error codes



npm i commonjs-walker

DownloadsWeekly Downloads






Last publish


  • avatar