Like grep, but more powerful than you can possibly imagine.
ast-grep is a structural code search and transformation tool that operates on Abstract Syntax Trees (ASTs) rather than raw text. Unlike traditional tools like grep or sed that use regular expressions, ast-grep understands the syntactic structure of your code, enabling you to find and modify patterns that would be impossible or impractical to match with text-based approaches. The npm package @ast-grep/napi provides Node.js bindings to the core Rust library, offering programmatic access to its AST manipulation capabilities.
The tool solves a fundamental problem in large codebases: reliably finding and refactoring code patterns across thousands of files. Text-based search fails when dealing with formatting variations, nested structures, or semantic equivalence. ast-grep parses code into its AST representation and matches patterns structurally, meaning it finds code by what it means, not just how it's written. This makes it invaluable for migrations, deprecations, and enforcing code standards.
ast-grep is particularly popular among library maintainers who need to provide migration scripts, platform teams building custom linting rules, and developers performing large-scale refactorings. Written in Rust with multi-core support, it processes tens of thousands of files in seconds while maintaining the simplicity of grep-like command-line usage. The package supports JavaScript, TypeScript, and numerous other languages through tree-sitter parsers.
The Node.js API provides jQuery-like methods for traversing and manipulating syntax nodes, with optional TypeScript type safety. It supports multiple matching strictness levels—from exact CST matching to relaxed signature matching—giving you control over how precisely patterns must align with target code. This flexibility makes ast-grep suitable for everything from quick ad-hoc searches to building sophisticated code transformation pipelines.
const { js } = require('@ast-grep/napi');
const sourceCode = `
function getUserData(id) {
return fetch('/api/users/' + id);
}
function getPostData(postId) {
return fetch('/api/posts/' + postId);
}
`;
const root = js.parse(sourceCode);
const pattern = 'fetch($URL + $ID)';
const matches = root.findAll(pattern);
console.log(`Found ${matches.length} string concatenation patterns in fetch calls`);
matches.forEach(match => {
const metaVars = match.getMultipleMatches();
console.log('Match:', match.text());
console.log('URL:', metaVars.URL.text());
console.log('ID:', metaVars.ID.text());
});
const transformed = root.replace(pattern, 'fetch(`${$URL}${$ID}`)');
console.log('\nTransformed code:');
console.log(transformed);Large-scale refactoring across codebases: When renaming APIs or updating function signatures across hundreds of files, ast-grep can find all usages structurally and apply transformations reliably, regardless of formatting or whitespace differences.
Custom linting rules for organization-specific patterns: Teams can define YAML-based rules to enforce architectural decisions, prevent deprecated API usage, or catch common bug patterns that standard ESLint rules miss, with built-in pretty error reporting.
Library migration automation: When upgrading major versions of dependencies, ast-grep can power codemods that automatically transform old API calls to new ones, handling complex nested patterns that regex-based tools struggle with.
Code quality analysis and metrics: Extract structural information from codebases to analyze complexity, identify code smells, or generate reports on specific patterns, all with better accuracy than text-based analysis.
Security auditing and vulnerability detection: Search for potentially unsafe code patterns like SQL injection vectors or insecure cryptographic usage by matching AST structures rather than fragile string patterns, reducing false positives.
npm install ast-greppnpm add ast-grepbun add ast-grep