acorn

ECMAScript parser

weekly downloads139.4M

versionv8.16.0

licenseMIT

categorytoolchain

Overview

Acorn is a JavaScript parser written in JavaScript that transforms ECMAScript source code into Abstract Syntax Trees (ASTs). It serves as the foundational parsing engine for major development tools including ESLint (via Espree), Webpack, Rollup, and numerous code analysis utilities. With over 139 million weekly downloads, it's one of the most widely deployed parsing libraries in the JavaScript ecosystem.

The library focuses on speed and standards compliance, supporting ECMAScript versions from ES3 through the latest specifications. Unlike heavier alternatives, Acorn maintains a small footprint while delivering fast parse times, making it ideal for processing large codebases or running in resource-constrained environments. Its core API centers around a parse() function that accepts source code and configuration options, returning a fully-formed AST conforming to the ESTree specification.

Acorn's extensibility sets it apart from monolithic parsers. The Parser.extend() method enables plugins to add custom syntax support (JSX, TypeScript annotations, stage-3 proposals) without forking the codebase. This plugin architecture has spawned an ecosystem of extensions like acorn-jsx for React and acorn-private-methods for class field proposals. Developers building transpilers, linters, code generators, or refactoring tools rely on Acorn's stable API and predictable AST output.

The package includes both programmatic APIs and a CLI utility for file parsing. Advanced options like locations, ranges, and token callbacks provide granular control over AST output, enabling precise source map generation and code transformation workflows. Whether you're building a JavaScript minifier, documentation generator, or custom linting rules, Acorn provides the low-level parsing infrastructure needed for robust source code manipulation.

Quick Start

typescript

const acorn = require('acorn');
const walk = require('acorn-walk');

const sourceCode = `
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}
const total = calculateTotal([{price: 10}, {price: 20}]);
`;

const ast = acorn.parse(sourceCode, {
  ecmaVersion: 2020,
  sourceType: 'module',
  locations: true,
  ranges: true
});

const functionCalls = [];
walk.simple(ast, {
  CallExpression(node) {
    if (node.callee.type === 'Identifier') {
      functionCalls.push({
        name: node.callee.name,
        line: node.loc.start.line,
        code: sourceCode.slice(node.range[0], node.range[1])
      });
    }
  }
});

console.log('Function calls found:', functionCalls);
console.log('AST root type:', ast.type);
console.log('Top-level statements:', ast.body.length);

Use Cases

Linters and Code Quality Tools: ESLint uses Acorn (through Espree) to parse JavaScript files into ASTs, enabling rule engines to traverse syntax trees and identify code smells, security vulnerabilities, or style violations. Custom linters can leverage Acorn's AST output to enforce organization-specific patterns.

Transpilers and Compilers: Tools like Babel and Rollup use Acorn to parse modern JavaScript syntax before transforming it to target environments. The AST representation allows systematic rewriting of language features (async/await to generators, ES modules to CommonJS) while preserving semantic correctness.

Code Refactoring and Codemods: Automated refactoring scripts parse codebases with Acorn, locate specific AST node patterns (function declarations, import statements), and programmatically rewrite them. Facebook's jscodeshift uses Acorn-compatible parsers for large-scale codebase migrations.

Static Analysis and Documentation: Documentation generators like JSDoc parsers extract function signatures, parameter types, and comments by traversing Acorn ASTs. Security scanners analyze control flow and data dependencies by examining the structured tree representation rather than fragile regex patterns.

Module Bundlers: Webpack and other bundlers parse JavaScript modules to detect import/export statements, build dependency graphs, and perform tree-shaking. Acorn's speed enables fast incremental parsing during watch mode, minimizing rebuild times in development workflows.

Pros & Cons

Pros

+Exceptional parsing speed with minimal memory footprint, outperforming most JavaScript parsers in benchmarks
+Highly extensible plugin system allows custom syntax support without forking, enabling JSX, TypeScript, and experimental features
+Industry-standard ESTree AST format ensures compatibility with tools like ESLint, Babel, and codemods
+Active maintenance with regular ECMAScript specification updates and a proven track record since 2012
+Comprehensive options for source location tracking (line/column, ranges) critical for error reporting and source maps

Cons

−Requires manual ecmaVersion configuration; defaults can cause parse errors with modern syntax if not specified
−Error messages, while accurate, are less descriptive than some alternatives like Babel parser for debugging syntax issues
−Plugin ecosystem requires understanding of tokenizer internals for advanced extensions beyond basic syntax additions
−No built-in support for TypeScript or JSX without plugins, unlike all-in-one parsers like @typescript-eslint/parser
−Documentation assumes familiarity with AST concepts; learning curve for developers new to parsing and compilers

Alternatives

@babel/parserv7.29.0

A JavaScript parser

toolchainbabeljavascript

117.1M / week

Install

bash

npm install acorn

bash

pnpm add acorn

bash

bun add acorn

Overview

Quick Start

typescript

const acorn = require('acorn');
const walk = require('acorn-walk');

const sourceCode = `
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}
const total = calculateTotal([{price: 10}, {price: 20}]);
`;

const ast = acorn.parse(sourceCode, {
  ecmaVersion: 2020,
  sourceType: 'module',
  locations: true,
  ranges: true
});

const functionCalls = [];
walk.simple(ast, {
  CallExpression(node) {
    if (node.callee.type === 'Identifier') {
      functionCalls.push({
        name: node.callee.name,
        line: node.loc.start.line,
        code: sourceCode.slice(node.range[0], node.range[1])
      });
    }
  }
});

console.log('Function calls found:', functionCalls);
console.log('AST root type:', ast.type);
console.log('Top-level statements:', ast.body.length);

Use Cases

Pros & Cons

Pros

+Exceptional parsing speed with minimal memory footprint, outperforming most JavaScript parsers in benchmarks
+Highly extensible plugin system allows custom syntax support without forking, enabling JSX, TypeScript, and experimental features
+Industry-standard ESTree AST format ensures compatibility with tools like ESLint, Babel, and codemods
+Active maintenance with regular ECMAScript specification updates and a proven track record since 2012
+Comprehensive options for source location tracking (line/column, ranges) critical for error reporting and source maps

Cons

−Requires manual ecmaVersion configuration; defaults can cause parse errors with modern syntax if not specified
−Error messages, while accurate, are less descriptive than some alternatives like Babel parser for debugging syntax issues
−Plugin ecosystem requires understanding of tokenizer internals for advanced extensions beyond basic syntax additions
−No built-in support for TypeScript or JSX without plugins, unlike all-in-one parsers like @typescript-eslint/parser
−Documentation assumes familiarity with AST concepts; learning curve for developers new to parsing and compilers