acorn vs estraverse
JavaScript AST Parsing and Traversal Tools
Search packages..
acornestraverseSimilar Packages:

JavaScript AST Parsing and Traversal Tools

acorn and estraverse are foundational utilities in the JavaScript tooling ecosystem, but they serve distinct roles in the Abstract Syntax Tree (AST) pipeline. acorn is a lightweight, fast JavaScript parser that converts source code into an ESTree-compliant AST. It focuses on the initial step of understanding code structure. estraverse, on the other hand, specializes in walking and modifying existing ASTs. It does not parse code itself but provides robust traversal methods like traverse and replace to inspect or transform the tree generated by parsers like acorn. Together, they form a complete solution for static analysis, linting, and code transformation tasks.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
acorn011,350559 kB15a month agoMIT
estraverse0966-394 years agoBSD-2-Clause

Acorn vs Estraverse: Parsing vs Traversal in the AST Pipeline

In the world of JavaScript tooling, understanding the difference between parsing code and walking the resulting tree is critical. acorn and estraverse are two industry-standard packages that handle these separate concerns. While they are often used together, they solve different problems. Let's break down their roles, APIs, and how they fit into a professional architecture.

🏗️ Core Responsibility: Generating vs Walking Trees

acorn is responsible for parsing. It takes raw source code strings and builds the initial AST. Without a parser like acorn, you cannot analyze code programmatically.

// acorn: Parsing source code into an AST
const acorn = require("acorn");

const code = "const x = 10;";
const ast = acorn.parse(code, { ecmaVersion: 2020 });

console.log(ast.type); // "Program"
console.log(ast.body[0].type); // "VariableDeclaration"

estraverse is responsible for traversal. It takes an existing AST (like the one acorn created) and walks through every node. It does not accept source code strings directly.

// estraverse: Walking an existing AST
const estraverse = require("estraverse");
const acorn = require("acorn");

const code = "const x = 10;";
const ast = acorn.parse(code, { ecmaVersion: 2020 });

estraverse.traverse(ast, {
  enter: function (node) {
    if (node.type === "VariableDeclaration") {
      console.log("Found variable declaration");
    }
  }
});

🛠️ API Design: Functional vs Visitor Pattern

acorn uses a functional API. You call a method with code and options, and it returns a result immediately. It is stateless and designed for one-off parsing tasks.

// acorn: Functional parsing call
const acorn = require("acorn");

// Parse a whole script
const ast1 = acorn.parse("let a = 1;", { ecmaVersion: 2020 });

// Parse a single expression at a specific index
const ast2 = acorn.parseExpressionAt("let a = 1;", 0, { ecmaVersion: 2020 });

estraverse uses a visitor pattern. You pass an object with enter and leave callbacks. This gives you control over what happens before and after processing a node's children.

// estraverse: Visitor pattern with enter/leave
const estraverse = require("estraverse");

estraverse.traverse(ast, {
  enter: function (node) {
    // Called before visiting children
    console.log("Entering:", node.type);
  },
  leave: function (node) {
    // Called after visiting children
    console.log("Leaving:", node.type);
  }
});

🔄 Modification: Read-Only vs Transformative

acorn produces a read-only structure. Its job ends once the AST is created. It does not provide methods to change the tree. If you need to modify the code, you must use a separate tool.

// acorn: No built-in modification methods
const acorn = require("acorn");
const ast = acorn.parse("let x = 1;", { ecmaVersion: 2020 });

// You cannot do ast.transform() with acorn alone
// You must manually manipulate the object or use a transformer

estraverse includes a replace method. This allows you to modify the tree during traversal. If your callback returns a new node, it swaps the old one out. This is essential for codemods or transpilers.

// estraverse: Transforming the AST
const estraverse = require("estraverse");

const newAst = estraverse.replace(ast, {
  enter: function (node) {
    if (node.type === "Literal" && node.value === 1) {
      // Replace '1' with '2'
      return {
        type: "Literal",
        value: 2,
        raw: "2"
      };
    }
  }
});

🔌 Extensibility: Plugins vs Custom Keys

acorn supports plugins to handle non-standard syntax. Since JavaScript evolves, acorn keeps the core small and lets plugins add support for JSX, TypeScript, or other proposals.

// acorn: Using plugins for JSX
const acorn = require("acorn");
const jsx = require("acorn-jsx");

const parser = acorn.Parser.extend(jsx());
const ast = parser.parse("<div>Hello</div>", { ecmaVersion: 2020 });

estraverse supports custom visitor keys. Some AST nodes (like custom ESLint rules or experimental features) might have children that estraverse doesn't know about by default. You can tell it which properties to traverse.

// estraverse: Defining custom visitor keys
const estraverse = require("estraverse");

estraverse.traverse(ast, {
  keys: {
    // Tell estraverse to look inside 'customProperty' for this node type
    CustomNode: ["customProperty"] 
  },
  enter: function (node) {
    // Logic here
  }
});

🚦 Control Flow: Breaking and Skipping

acorn handles errors by throwing exceptions. If the code is invalid, parsing stops immediately. You can catch these errors to provide feedback, but you cannot partially parse invalid code without special plugins.

// acorn: Error handling
const acorn = require("acorn");

try {
  acorn.parse("let x = ", { ecmaVersion: 2020 });
} catch (err) {
  console.log("Parse error:", err.message);
  // Parsing stops here
}

estraverse allows you to control the walk. You can return specific symbols to break the loop or skip a node's children. This is useful for performance optimization when you find what you need early.

// estraverse: Controlling traversal flow
const estraverse = require("estraverse");

estraverse.traverse(ast, {
  enter: function (node) {
    if (node.type === "VariableDeclaration") {
      // Skip children of this node
      return estraverse.VisitorOption.Skip; 
    }
    if (node.type === "Program") {
      // Stop the entire traversal
      return estraverse.VisitorOption.Break;
    }
  }
});

🤝 Similarities: Shared Ground Between Acorn and Estraverse

While their jobs differ, both packages share design philosophies that make them work well together.

1. 🌳 ESTree Compliance

  • Both adhere to the ESTree specification for AST shapes.
  • This ensures acorn output works seamlessly with estraverse input.
// Both use standard 'type' property for node identification
const node = { type: "Identifier", name: "x" };
// Acorn produces this shape
// Estraverse expects this shape

2. ⚡ Performance Focused

  • Both are designed to be lightweight and fast.
  • They avoid heavy dependencies, making them suitable for CLI tools and browsers.
// Both are commonly used in bundlers like Webpack or Rollup
// due to their low overhead

3. 🛠️ Node.js and Browser Compatible

  • Both run in Node.js environments and browsers.
  • This flexibility allows tools to run server-side during build or client-side in dev tools.
// Can be imported via CommonJS or ES Modules in both environments
import acorn from 'acorn';
import estraverse from 'estraverse';

4. ✅ Mature and Stable

  • Both have been battle-tested in major tools (ESLint, Babel, Terser).
  • APIs are stable, reducing the risk of breaking changes in your tooling.
// APIs have remained consistent over many years
// acorn.parse(...) and estraverse.traverse(...) are reliable

5. 👥 Community Ecosystem

  • Both have rich plugin ecosystems.
  • Many tools build extensions specifically for these packages.
// Examples of ecosystem tools
// acorn-walk (official walker by Acorn team)
// estraverse (standalone walker used by many)

📊 Summary: Key Similarities

FeatureShared by Acorn and Estraverse
AST Standard🌳 ESTree compliant
Environment🌐 Node.js & Browser
Performance⚡ Lightweight, fast
Stability✅ Mature, stable APIs
Ecosystem👥 Widely adopted in tooling

🆚 Summary: Key Differences

Featureacornestraverse
Primary Role📝 Parsing Code to AST🚶 Walking/Modifying AST
Input📄 Source Code String🌳 AST Object
Output🌳 AST Object🌳 Modified AST or Void
Modification❌ Read-only result✅ replace method available
Flow Control⚠️ Throws on error🛑 Break/Skip options
Extensibility🔌 Plugins for syntax🔑 Custom visitor keys

💡 The Big Picture

acorn is the gatekeeper 🚪. It sits at the start of your pipeline, turning text into structure. Use it when you need to read code. It is fast, strict, and reliable for generating the map of your codebase.

estraverse is the worker 🛠️. It takes that map and does the heavy lifting of inspection or renovation. Use it when you need to find specific patterns or change the structure. It handles the complex recursion logic so you don't have to.

Final Thought: In most professional tooling setups, you do not choose one over the other. You use acorn to create the AST and estraverse to walk it. Understanding where one ends and the other begins is key to building robust static analysis or transformation tools.

How to Choose: acorn vs estraverse

  • acorn:

    Choose acorn when your primary need is to convert JavaScript source code into an AST. It is the ideal starting point for tools that need to read code, such as linters, bundlers, or custom static analyzers. Its small footprint and speed make it suitable for environments where performance matters, like browser-based editors or CLI tools. If you need to support modern ECMAScript features or JSX via plugins, acorn provides a stable and extensible parsing core.

  • estraverse:

    Choose estraverse when you already have an AST and need to walk through it or modify its structure. It is the right choice for implementing transformations, such as refactoring scripts, injecting code, or extracting metadata from a tree produced by acorn or esprima. If your task involves visiting every node, filtering specific patterns, or replacing nodes recursively, estraverse handles the recursion logic so you can focus on the node-specific rules.

Similar Npm Packages to acorn

acorn is a small, fast, and efficient JavaScript parser written in JavaScript. It is designed to parse ECMAScript (JavaScript) code and generate an Abstract Syntax Tree (AST) that can be used for various purposes, such as code analysis, transformation, or linting. Acorn is known for its speed and flexibility, making it a popular choice among developers who need a lightweight solution for parsing JavaScript.

While Acorn is a powerful tool, there are alternatives available that also serve the purpose of parsing JavaScript code. Here are a couple of notable alternatives:

  • esprima is another popular JavaScript parser that is known for its compliance with the ECMAScript specification. It generates a comprehensive AST and is often used in tools that require a deep understanding of JavaScript syntax. Esprima is particularly valued for its accuracy and adherence to the latest ECMAScript standards. If you need a parser that strictly follows the ECMAScript specification and provides detailed error reporting, Esprima is a solid choice.
  • typescript is primarily known as a superset of JavaScript that adds static typing to the language. However, it also includes a powerful parser that can analyze and transform JavaScript and TypeScript code. TypeScript's parser is particularly useful if you are working in a TypeScript environment or need to handle both TypeScript and JavaScript codebases. Its type-checking capabilities can help catch errors early in the development process, making it a great option for larger projects.

To see how Acorn compares with Esprima and TypeScript, check out the comparison: Comparing acorn vs esprima vs typescript.

README for acorn

Acorn

A tiny, fast JavaScript parser written in JavaScript.

Community

Acorn is open source software released under an MIT license.

You are welcome to report bugs or create pull requests on github.

Installation

The easiest way to install acorn is from npm:

npm install acorn

Alternately, you can download the source and build acorn yourself:

git clone https://github.com/acornjs/acorn.git
cd acorn
npm install

Importing acorn

ESM as well as CommonJS is supported for all 3: acorn, acorn-walk and acorn-loose.

ESM example for acorn:

import * as acorn from "acorn"

CommonJS example for acorn:

let acorn = require("acorn")

ESM is preferred, as it allows better editor auto-completions by offering TypeScript support. For this reason, following examples will use ESM imports.

Interface

parse(input, options) is the main interface to the library. The input parameter is a string, options must be an object setting some of the options listed below. The return value will be an abstract syntax tree object as specified by the ESTree spec.

import * as acorn from "acorn"
console.log(acorn.parse("1 + 1", {ecmaVersion: 2020}))

When encountering a syntax error, the parser will raise a SyntaxError object with a meaningful message. The error object will have a pos property that indicates the string offset at which the error occurred, and a loc object that contains a {line, column} object referring to that same position.

Options are provided by in a second argument, which should be an object containing any of these fields (only ecmaVersion is required):

  • ecmaVersion: Indicates the ECMAScript version to parse. Can be a number, either in year (2022) or plain version number (6) form, or "latest" (the latest the library supports). This influences support for strict mode, the set of reserved words, and support for new syntax features.

    NOTE: Only 'stage 4' (finalized) ECMAScript features are being implemented by Acorn. Other proposed new features must be implemented through plugins.

  • sourceType: Indicate the mode the code should be parsed in. Can be either "script", "module" or "commonjs". This influences global strict mode and parsing of import and export declarations.

    NOTE: If set to "module", then static import / export syntax will be valid, even if ecmaVersion is less than 6. If set to "commonjs", it is the same as "script" except that the top-level scope behaves like a function.

  • onInsertedSemicolon: If given a callback, that callback will be called whenever a missing semicolon is inserted by the parser. The callback will be given the character offset of the point where the semicolon is inserted as argument, and if locations is on, also a {line, column} object representing this position.

  • onTrailingComma: Like onInsertedSemicolon, but for trailing commas.

  • allowReserved: If false, using a reserved word will generate an error. Defaults to true for ecmaVersion 3, false for higher versions. When given the value "never", reserved words and keywords can also not be used as property names (as in Internet Explorer's old parser).

  • allowReturnOutsideFunction: By default, a return statement at the top level raises an error. Set this to true to accept such code.

  • allowImportExportEverywhere: By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed, and also allows import.meta expressions to appear in scripts (when sourceType is not "module").

  • allowAwaitOutsideFunction: If false, await expressions can only appear inside async functions. Defaults to true in modules for ecmaVersion 2022 and later, false for lower versions. Setting this option to true allows to have top-level await expressions. They are still not allowed in non-async functions, though. Setting this option to true is not allowed when sourceType: "commonjs".

  • allowSuperOutsideMethod: By default, super outside a method raises an error. Set this to true to accept such code.

  • allowHashBang: When this is enabled, if the code starts with the characters #! (as in a shellscript), the first line will be treated as a comment. Defaults to true when ecmaVersion >= 2023.

  • checkPrivateFields: By default, the parser will verify that private properties are only used in places where they are valid and have been declared. Set this to false to turn such checks off.

  • locations: When true, each node has a loc object attached with start and end subobjects, each of which contains the one-based line and zero-based column numbers in {line, column} form. Default is false.

  • onToken: If a function is passed for this option, each found token will be passed in same format as tokens returned from tokenizer().getToken().

    If array is passed, each found token is pushed to it.

    Note that you are not allowed to call the parser from the callback—that will corrupt its internal state.

  • onComment: If a function is passed for this option, whenever a comment is encountered the function will be called with the following parameters:

    • block: true if the comment is a block comment, false if it is a line comment.
    • text: The content of the comment.
    • start: Character offset of the start of the comment.
    • end: Character offset of the end of the comment.

    When the locations options is on, the {line, column} locations of the comment’s start and end are passed as two additional parameters.

    If array is passed for this option, each found comment is pushed to it as object in Esprima format:

    {
  "type": "Line" | "Block",
  "value": "comment text",
  "start": Number,
  "end": Number,
  // If `locations` option is on:
  "loc": {
    "start": {line: Number, column: Number}
    "end": {line: Number, column: Number}
  },
  // If `ranges` option is on:
  "range": [Number, Number]
}

    Note that you are not allowed to call the parser from the callback—that will corrupt its internal state.

  • ranges: Nodes have their start and end characters offsets recorded in start and end properties (directly on the node, rather than the loc object, which holds line/column data. To also add a semi-standardized range property holding a [start, end] array with the same numbers, set the ranges option to true.

  • program: It is possible to parse multiple files into a single AST by passing the tree produced by parsing the first file as the program option in subsequent parses. This will add the toplevel forms of the parsed file to the "Program" (top) node of an existing parse tree.

  • sourceFile: When the locations option is true, you can pass this option to add a source attribute in every node’s loc object. Note that the contents of this option are not examined or processed in any way; you are free to use whatever format you choose.

  • directSourceFile: Like sourceFile, but a sourceFile property will be added (regardless of the location option) directly to the nodes, rather than the loc object.

  • preserveParens: If this option is true, parenthesized expressions are represented by (non-standard) ParenthesizedExpression nodes that have a single expression property containing the expression inside parentheses.

parseExpressionAt(input, offset, options) will parse a single expression in a string, and return its AST. It will not complain if there is more of the string left after the expression.

tokenizer(input, options) returns an object with a getToken method that can be called repeatedly to get the next token, a {start, end, type, value} object (with added loc property when the locations option is enabled and range property when the ranges option is enabled). When the token's type is tokTypes.eof, you should stop calling the method, since it will keep returning that same token forever.

Note that tokenizing JavaScript without parsing it is, in modern versions of the language, not really possible due to the way syntax is overloaded in ways that can only be disambiguated by the parse context. This package applies a bunch of heuristics to try and do a reasonable job, but you are advised to use parse with the onToken option instead of this.

In ES6 environment, returned result can be used as any other protocol-compliant iterable:

for (let token of acorn.tokenizer(str)) {
  // iterate over the tokens
}

// transform code to array of tokens:
var tokens = [...acorn.tokenizer(str)]

tokTypes holds an object mapping names to the token type objects that end up in the type properties of tokens.

getLineInfo(input, offset) can be used to get a {line, column} object for a given program string and offset.

The Parser class

Instances of the Parser class contain all the state and logic that drives a parse. It has static methods parse, parseExpressionAt, and tokenizer that match the top-level functions by the same name.

When extending the parser with plugins, you need to call these methods on the extended version of the class. To extend a parser with plugins, you can use its static extend method.

var acorn = require("acorn")
var jsx = require("acorn-jsx")
var JSXParser = acorn.Parser.extend(jsx())
JSXParser.parse("foo(<bar/>)", {ecmaVersion: 2020})

The extend method takes any number of plugin values, and returns a new Parser class that includes the extra parser logic provided by the plugins.

Command line interface

The bin/acorn utility can be used to parse a file from the command line. It accepts as arguments its input file and the following options:

  • --ecma3|--ecma5|--ecma6|--ecma7|--ecma8|--ecma9|--ecma10: Sets the ECMAScript version to parse. Default is version 9.

  • --module: Sets the parsing mode to "module". Is set to "script" otherwise.

  • --locations: Attaches a "loc" object to each node with "start" and "end" subobjects, each of which contains the one-based line and zero-based column numbers in {line, column} form.

  • --allow-hash-bang: If the code starts with the characters #! (as in a shellscript), the first line will be treated as a comment.

  • --allow-await-outside-function: Allows top-level await expressions. See the allowAwaitOutsideFunction option for more information.

  • --compact: No whitespace is used in the AST output.

  • --silent: Do not output the AST, just return the exit status.

  • --help: Print the usage information and quit.

The utility spits out the syntax tree as JSON data.

Existing plugins

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.