docs: Guide for ExternalModule

docs/building-with-codegen/external-modules.mdx

@@ -0,0 +1,119 @@
+---
+title: "External Modules"
+sidebarTitle: "External Modules"
+icon: "box-archive"
+iconType: "solid"
+---
+
+Codegen provides a way to handle imports from external packages and modules through the [ExternalModule](/api-reference/core/ExternalModule) class.
+
+```python
+# Python examples
+import datetime
+from requests import get
+
+# TypeScript/JavaScript examples
+import React from 'react'
+import { useState, useEffect } from 'react'
+import type { ReactNode } from 'react'
+import axios from 'axios'
+```
+
+## What are External Modules?
+
+When writing code, you often import from packages that aren't part of your project - like `datetime` and `requests` in Python, or `react` and `axios` in TypeScript. In Codegen, these are represented as [ExternalModule](/api-reference/core/ExternalModule) instances.
+
+```python
+for imp in codebase.imports:
+    if isinstance(imp.symbol, ExternalModule):
+        print(f"Importing from external package: {imp.resolved_symbol.source}")
+```
+
+<Note>
+  External modules are read-only - you can analyze them but can't modify their
+  implementation. This makes sense since they live in your project's
+  dependencies!
+</Note>
+
+## Working with External Modules
+
+The most common use case is handling external modules differently from your project's code:
+
+### Identifying Function Calls as External Modules
+
+For [FunctionCall](/api-reference/core/FunctionCall) instances, you can check if the function definition is an [ExternalModule](/api-reference/core/ExternalModule) via the [FunctionCall.function_definition](/api-reference/core/FunctionCall#function-definition) property:
+
+```python
+for fcall in file.function_calls:
+    definition = fcall.function_definition
+    if isinstance(definition, ExternalModule):
+        # Skip external functions
+        print(f'External function: {definition.name}')
+    else:
+        # Process local functions...
+        print(f'Local function: {definition.name}')
+```
+
+### Import Resolution
+
+Similarly, when working with imports, you can determine if they resolve to external modules by checking the [Import.resolved_symbol](/api-reference/core/Import#resolved-symbol) property:
+
+```python
+for imp in file.imports:
+    resolved = imp.resolved_symbol
+    if isinstance(resolved, ExternalModule):
+        print(f"Import from external package: from {imp.module} import {imp.name}")
+```
+
+<Tip>
+  Use `isinstance(symbol, ExternalModule)` to reliably identify external
+  modules. This works better than checking names or paths since it handles all
+  edge cases.
+</Tip>
+
+## Properties and Methods
+
+External modules provide several useful properties:
+
+```python
+# Get the module name
+module_name = external_module.name  # e.g. "datetime" or "useState"
+
+# Check if it's from node_modules (TypeScript/JavaScript)
+if external_module.filepath == "":
+    print("This is an external package from node_modules")
+```
+
+## Common Patterns
+
+Here are some typical ways you might work with external modules:
+
+### Skip External Processing:
+
+When modifying function calls or imports, skip external modules since they can't be changed:
+
+```python
+# Example from a codemod that adds type hints
+def add_type_hints(function):
+    if isinstance(function.definition, ExternalModule):
+        return  # Can't add type hints to external modules like React.FC
+    # Add type hints to local functions...
+```
+
+### Analyze Dependencies
+
+Track which external packages your code uses:
+
+```python
+# Find all external package dependencies
+external_deps = set()
+for imp in codebase.imports:
+    if isinstance(imp.resolved_symbol, ExternalModule):
+        external_deps.add(imp.resolved_symbol.source)
+        # Will find things like 'react', 'lodash', 'datetime', etc.
+```
+
+<Note>
+  When working with imports, always handle external modules as a special case.
+  This ensures your codemods work correctly with both local and external code.
+</Note>

docs/mint.json

@@ -102,6 +102,7 @@
 				"building-with-codegen/variable-assignments",
 				"building-with-codegen/local-variables",
 				"building-with-codegen/comments-and-docstrings",
+				"building-with-codegen/external-modules",
 				"building-with-codegen/moving-symbols",
 				"building-with-codegen/collections",
 				"building-with-codegen/traversing-the-call-graph",