> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# Import and Require Detection

> Utilities for finding and analyzing module import and require statements

Utilities for finding ES module imports, CommonJS requires, and dynamic imports for specific Node.js modules.

## Overview

These utilities help locate module dependencies in different formats:

* **ES Module Imports**: `import fs from 'fs'` or `import { readFile } from 'node:fs'`
* **CommonJS Requires**: `const fs = require('fs')` or `const { readFile } = require('node:fs')`
* **Dynamic Imports**: `const fs = await import('fs')`

<Note>
  All detection functions automatically support both bare module names (`'fs'`) and `node:` prefixed imports (`'node:fs'`).
</Note>

## Core Functions

### getModuleDependencies

Finds all module import/require statements for a specific Node.js module. This is the most comprehensive function that combines results from all other detection methods.

```typescript theme={null}
import { getModuleDependencies } from '@nodejs/codemod-utils/ast-grep/module-dependencies';

const ast = context.getAST();
const fsImports = getModuleDependencies(ast, 'fs');

// Finds:
// - import fs from 'fs';
// - import { readFile } from 'node:fs';
// - const fs = require('fs')
// - const fs = await import('fs')
```

<ParamField path="rootNode" type="SgRoot<Js>" required>
  The root AST node to search
</ParamField>

<ParamField path="nodeModuleName" type="string" required>
  The Node.js module name to search for (e.g., 'fs', 'path', 'util')
</ParamField>

**Returns**: `SgNode<Js>[]` - Array of nodes representing all import/require statements for the module

<Note>
  Under the hood, this function calls `getNodeRequireCalls`, `getNodeImportStatements`, and `getNodeImportCalls`, then combines the results.
</Note>

## ES Module Import Detection

### getNodeImportStatements

Finds all ES module import statements for a specific Node.js module.

```typescript theme={null}
import { getNodeImportStatements } from '@nodejs/codemod-utils/ast-grep/import-statement';

// Finds: import fs from 'fs';
// Finds: import { readFile } from 'node:fs';
// Finds: import * as fs from 'fs';
const fsImports = getNodeImportStatements(ast, 'fs');
```

<ParamField path="rootNode" type="SgRoot<Js>" required>
  The root AST node to search
</ParamField>

<ParamField path="nodeModuleName" type="string" required>
  The Node.js module name to search for
</ParamField>

**Returns**: `SgNode<Js>[]` - Array of `import_statement` nodes

### getNodeImportCalls

Finds dynamic import calls assigned to variables. Excludes unassigned imports.

```typescript theme={null}
import { getNodeImportCalls } from '@nodejs/codemod-utils/ast-grep/import-statement';

// Finds: const fs = await import('node:fs');
// Finds: import('fs').then(fs => ...);
// Ignores: import('fs'); // unassigned
const fsImportCalls = getNodeImportCalls(ast, 'fs');
```

<ParamField path="rootNode" type="SgRoot<Js>" required>
  The root AST node to search
</ParamField>

<ParamField path="nodeModuleName" type="string" required>
  The Node.js module name to search for
</ParamField>

**Returns**: `SgNode<Js>[]` - Array of `variable_declarator` or `expression_statement` nodes with import calls

<Note>
  This function captures both `const fs = await import('fs')` patterns and `.then()` chained patterns like `import('fs').then(...)`, but ignores simple unassigned `import('fs')` calls.
</Note>

## CommonJS Require Detection

### getNodeRequireCalls

Finds CommonJS require calls assigned to variables.

```typescript theme={null}
import { getNodeRequireCalls } from '@nodejs/codemod-utils/ast-grep/require-call';

// Finds: const fs = require('fs');
// Finds: const { readFile } = require('node:fs');
// Finds: const readFile = require('fs').readFile;
const fsRequires = getNodeRequireCalls(ast, 'fs');
```

<ParamField path="rootNode" type="SgRoot<Js>" required>
  The root AST node to search
</ParamField>

<ParamField path="nodeModuleName" type="string" required>
  The Node.js module name to search for
</ParamField>

**Returns**: `SgNode<Js>[]` - Array of `variable_declarator` nodes with require calls

<Note>
  Simple `require('fs')` calls without variable assignment are not captured, as they have no effect in codemod context.
</Note>

## Usage Examples

### Finding All FS Module Usage

```typescript theme={null}
const ast = context.getAST();
const allFsUsage = getModuleDependencies(ast, 'fs');

if (allFsUsage.length > 0) {
  console.log(`Found ${allFsUsage.length} fs module imports/requires`);
  
  for (const usage of allFsUsage) {
    console.log(usage.text());
  }
}
```

### Detecting Import Style

```typescript theme={null}
const esImports = getNodeImportStatements(ast, 'util');
const cjsRequires = getNodeRequireCalls(ast, 'util');
const dynamicImports = getNodeImportCalls(ast, 'util');

if (esImports.length > 0 && cjsRequires.length > 0) {
  console.warn('Mixed import styles detected!');
}
```

### Processing All Module Imports

```typescript theme={null}
import { getModuleDependencies } from '@nodejs/codemod-utils/ast-grep/module-dependencies';
import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';

const utilImports = getModuleDependencies(ast, 'util');

for (const importNode of utilImports) {
  // Resolve how types.isNativeError should be accessed
  const path = resolveBindingPath(importNode, '$.types.isNativeError');
  
  if (path) {
    console.log(`Access pattern: ${path}`);
    // Could be: 'types.isNativeError', 'util.types.isNativeError', etc.
  }
}
```

### Migration Example: Consolidating Imports

```typescript theme={null}
const fsImports = getModuleDependencies(ast, 'fs');

if (fsImports.length > 1) {
  // Multiple fs imports detected - could consolidate them
  console.log('Consider consolidating multiple fs imports');
  
  const allBindings = [];
  for (const imp of fsImports) {
    // Extract bindings from each import
    const bindings = imp.findAll({
      rule: { kind: 'identifier' }
    });
    allBindings.push(...bindings.map(b => b.text()));
  }
  
  console.log('All bindings:', allBindings);
}
```