Tree Analysis

The main dependency tree analysis functionality provides comprehensive dependency mapping with support for circular dependency detection, configurable filtering, and extensive customization options for different module systems and build tools.

Core Function

function dependencyTree(options: Options): Tree;

Parameters

• filename (string, required): Absolute or relative path to the entry point file to analyze
• directory (string, required): Root directory containing all the files to be analyzed
• visited (Tree, optional): Cache object for memoization to avoid reprocessing files
• nonExistent (string[], optional): Array to collect dependencies that could not be resolved
• isListForm (boolean, optional): When true, returns array instead of object tree
• requireConfig (string, optional): Path to RequireJS configuration file for AMD module resolution
• webpackConfig (string, optional): Path to Webpack configuration file for alias resolution
• nodeModulesConfig (object, optional): Configuration for resolving entry files in node_modules
• detectiveConfig (object, optional): Options passed to precinct for AST parsing customization
• tsConfig (string | object, optional): TypeScript configuration file path or parsed config object
• noTypeDefinitions (boolean, optional): Resolve to .js files instead of .d.ts for TypeScript imports
• filter (function, optional): Function to determine if a module should be included in the tree

Returns

Returns a Tree object representing the complete dependency structure:

interface TreeInnerNode {
  [parent: string]: TreeInnerNode | string;
}

type Tree = TreeInnerNode | string;

The tree is a nested object where each key is an absolute file path and the value is either another nested object (subtree) or a string (leaf node).

Usage Examples

Basic Tree Analysis

const dependencyTree = require('dependency-tree');

const tree = dependencyTree({
  filename: './src/index.js',
  directory: './src'
});

console.log(tree);
// Output:
// {
//   '/absolute/path/to/src/index.js': {
//     '/absolute/path/to/src/utils.js': {},
//     '/absolute/path/to/src/config.js': {
//       '/absolute/path/to/src/constants.js': {}
//     }
//   }
// }

With Filtering

const tree = dependencyTree({
  filename: './src/index.js',
  directory: './src',
  filter: (path) => !path.includes('node_modules') // Exclude node_modules
});

TypeScript Project

const tree = dependencyTree({
  filename: './src/app.ts',
  directory: './src',
  tsConfig: './tsconfig.json'
});

Webpack Project with Aliases

const tree = dependencyTree({
  filename: './src/index.js',
  directory: './src',
  webpackConfig: './webpack.config.js'
});

Configuration Details

RequireJS Configuration

When analyzing AMD modules, provide a RequireJS config to resolve module aliases:

const tree = dependencyTree({
  filename: './app.js',
  directory: './js',
  requireConfig: './require.config.js'
});

Detective Configuration

Customize AST parsing behavior for different module types:

const tree = dependencyTree({
  filename: './src/app.js',
  directory: './src',
  detectiveConfig: {
    amd: {
      skipLazyLoaded: true
    },
    es6: {
      mixedImports: true
    }
  }
});

Node Modules Configuration

Control how entry points are resolved in node_modules:

const tree = dependencyTree({
  filename: './src/app.js',
  directory: './src',
  nodeModulesConfig: {
    entry: 'module' // Use 'module' field instead of 'main'
  }
});

Error Handling

The function handles various error scenarios gracefully:

• File Not Found: Returns empty object {} if the entry file doesn't exist
• Circular Dependencies: Automatically detected and prevented from causing infinite loops
• Resolution Failures: Unresolvable dependencies are added to the nonExistent array
• Parse Errors: AST parsing errors are caught and logged, skipping problematic files

Performance Considerations

• Memoization: Use the visited parameter to cache results across multiple calls
• Filtering: Apply filters early to reduce the traversal scope
• Configuration Reuse: Reuse parsed TypeScript configurations for better performance

Advanced Usage

Tracking Non-existent Dependencies

const nonExistent = [];
const tree = dependencyTree({
  filename: './src/app.js',
  directory: './src',
  nonExistent
});

console.log('Missing dependencies:', nonExistent);

Custom Filter Function

const tree = dependencyTree({
  filename: './src/app.js',
  directory: './src',
  filter: (filePath, parentPath) => {
    // Include only files in src directory
    return filePath.includes('/src/') && 
           !filePath.includes('test') &&
           !filePath.includes('spec');
  }
});