Acorn: a JavaScript parser written in JavaScript

What Acorn parses, and who needs that

Acorn turns JavaScript source text into a syntax tree. That is the whole job. The README calls it "a tiny, fast JavaScript parser, written completely in JavaScript", and the repository splits the work across three packages: acorn, the main parser; acorn-loose, described as the error-tolerant parser; and acorn-walk, the syntax tree walker. The audience is narrow and technical. If you are writing a linter, a minifier, a bundler transform, a codemod, a syntax highlighter or an editor extension, you need a parser as a library, and you need it to run in the same process as the rest of your tool. Acorn targets exactly that. The README documents no CLI, config file format or service. The bin/ directory exists in the repository, but package.json uses it only for scripts that generate Unicode data and run test262, not as a user-facing command. So the entry point for a user is the npm package, not a binary.

The plugin model: extending Parser instead of forking it

The interesting design decision is how dialects are handled. Acorn does not try to parse everything. Instead, the README says plugins "can, within reasonable bounds, redefine the way the parser works", adding token types, tokenizer contexts and methods on the parser object. A plugin is a function from a parser class to an extended parser class. Since applying plugins one by one gets awkward, the static method Parser.extend takes any number of plugin values and returns a class extended by all of them. The README advises creating that extended class once and reusing it, so the JavaScript engine's optimizer is not repeatedly confused by new class shapes. The README is blunt about the cost: this "is not a clean, elegant API", it requires understanding Acorn's internals, and plugins are likely to break when those internals change significantly. That is a real trade-off, not a marketing line. You get the ability to parse JavaScript dialects without maintaining a fork, and you pay for it with an extension surface that carries no stability promise. The README also notes that in principle plugins can be combined, giving the example of a types plugin and a JSX plugin loaded together, but it presents that as a possibility rather than a guarantee.

Building acorn from source and loading a plugin

The README gives one set of install steps, and they are for working on the repository rather than for consuming the published package. It says that to build the content of the repository you run npm install, after cloning. That sequence is the only install procedure the README documents.

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

The README does not document an npm install acorn command for consumers; it points at the npm package through a badge and lists acorn among the three packages the repository holds. The code example the README does give is for plugin composition, using Parser.extend with acorn-jsx and acorn-bigint, and it is worth reading closely because it shows the shape of the API: the extended class is built once, then parse is called on it.

const {Parser} = require("acorn")

const MyParser = Parser.extend(
  require("acorn-jsx")(),
  require("acorn-bigint")
)
console.log(MyParser.parse("// Some bigint + JSX code"))

The README also shows what a trivial plugin looks like: a function that takes a Parser class and returns a subclass overriding readToken, calling super.readToken(code). That is the extension seam in its smallest form.

Where Acorn is the wrong tool

The clearest limitation is dialect coverage. TypeScript and JSX are not part of the core parser as described in the README; they are plugin territory, and the plugin API is explicitly unstable. If your project parses modern TypeScript daily, you are depending on a third-party plugin tracking Acorn's internals, and the README tells you those plugins are likely to break when internals change. That is a maintenance liability you should price in before adopting. The second limitation is that Acorn is a parser, not a compiler or a type checker. It produces a tree. It does not resolve scopes for you, does not type-check, and does not transform. The README does not claim otherwise, but teams sometimes reach for a parser expecting analysis and find they still have to build the analysis layer. Third, error recovery is a separate package. If you are parsing user-supplied code in an editor and need partial results from broken input, the main parser is not the thing you want; acorn-loose is, and the README gives it one line of description. Fourth, there is no CLI documented for end users, so any command-line parsing workflow has to be built around the library.

Acorn against a hand-written recursive descent parser

The realistic alternative is not another named library but writing your own parser, or using the parser embedded in whatever compiler toolchain you already depend on. A hand-written recursive descent parser gives you total control over the grammar, the node shapes and the error messages, and it has no dependency surface at all. The difference in approach is stark. Acorn gives you a maintained tokenizer, a grammar covering the JavaScript language, and a plugin seam for dialects, at the cost of an extension API the README calls unclean and internals you must learn to use it. A bespoke parser gives you a clean API by construction, because you designed it, but you own every new syntax proposal the language adds and every Unicode identifier rule, and the repository shows how much of that is mechanical work: the package.json scripts include generate:identifier-regex and generate:unicode-script-values, both run through node bin/, and the devDependencies pin @unicode/unicode-18.0.0. Most teams should not rebuild that. The teams that should are the ones whose grammar diverges far enough from JavaScript that plugin patching becomes more work than a fresh implementation.

Maintenance cost, licence and what to check

The repository is not archived, and the last push was on 2026-10-21. That says nothing about release cadence; the repository has no published GitHub releases. The dependency list in package.json is a useful signal of what you inherit if you build from source: rollup for bundling, eslint with neostandard for linting, and test262 pinned to a specific git commit for conformance testing. Those are devDependencies, so a consumer installing the published package does not pull them in. The licence is MIT according to package.json, and the README links to acorn/LICENSE and states the same. MIT is permissive and imposes no source-disclosure requirement, but this is a description of the file, not legal advice; if you are redistributing a bundled copy, read the licence text and your own obligations. One gap worth noting: the README's build section tells you to run npm install at the repository root but does not spell out the Node version.

Editorial conclusion

Acorn fits tools that need a JavaScript syntax tree inside a JavaScript process: linters, bundler plugins, code transformers, editor extensions. It is the wrong choice if you need to parse TypeScript or JSX out of the box, since the README treats those as plugin territory, and it is the wrong choice if you want a documented, stable extension contract, because the README itself warns that plugins reach into internals and break when those internals change. Before adopting it, verify which of the three packages you actually need, whether the dialect plugin you depend on is still compatible with the Acorn version you install, and whether the MIT licence in package.json matches the terms your distribution channel expects.

Frequently asked questions

Official sources

1. acornjs/acorn on GitHub
2. Issues
3. README