Acorn with Node.js Syntax Plugins

2.0.1 verified Sun Apr 19 auth: no javascript

acorn-node is a JavaScript parser library that bundles the core Acorn parser with a set of preloaded plugins, providing syntax parity with recent Node.js versions. This includes support for features like BigInt, numeric separators, public and private class fields (instance and static), dynamic `import()`, `import.meta`, and `export * as ns from`. The package sets default options like `ecmaVersion: 2019`, `allowHashBang: true`, and `allowReturnOutsideFunction: true` to align with Node.js module semantics. The current stable version is 2.0.1. Releases appear to follow Acorn's updates and Node.js syntax advancements, with minor patch releases addressing specific parsing issues. Its key differentiator is providing a ready-to-use Acorn instance capable of parsing modern Node.js JavaScript without requiring manual plugin configuration, including compatibility for older Node.js versions via Bublé-compiled plugins.

Common errors

error SyntaxError: Unexpected token (XX:YY) ↓

cause Attempting to parse modern JavaScript syntax (e.g., class fields, BigInt) with a plain `acorn` instance or an outdated `acorn-node` version.

fix

Ensure you are using acorn-node (current version 2.0.1 or higher) and not acorn directly, as acorn-node preloads the necessary plugins. Also, verify sourceType is correctly set in parsing options (e.g., 'module' for ES modules).

error TypeError: Cannot read properties of undefined (reading 'type') or similar errors when traversing AST for dynamic imports. ↓

cause Code expecting `Import` nodes for dynamic imports when using `acorn-node` v2.0.0 or later, which switched to `ImportExpression`.

fix

Update your AST traversal logic to look for ImportExpression nodes instead of Import nodes. Example: if (node.type === 'ImportExpression') { ... }.

error ReferenceError: require is not defined or SyntaxError: Cannot use import statement outside a module ↓

cause Mixing CommonJS `require()` and ESM `import` statements or running code in an environment that doesn't support the chosen module system.

fix

For Node.js environments, ensure consistency: either use require() exclusively (and save files as .js if type: module isn't in package.json) or use import exclusively (and save files as .mjs or ensure type: module in package.json). For browser environments, use bundlers or ensure script tags have type='module' for ESM.

Warnings

breaking The node type for dynamic `import()` expressions changed from `Import` to `ImportExpression`. This aligns with the standard Acorn/ESTree AST specification. ↓

fix Update AST traversal logic to check for `ImportExpression` nodes instead of `Import` nodes when handling dynamic imports.

gotcha When `acorn-node` upgraded to Acorn v7 (in `acorn-node` v1.8.0), it initially maintained the `Import` node type for dynamic imports for backwards compatibility, deviating from Acorn v7's `ImportExpression`. This could lead to confusion if integrating with other tools expecting standard Acorn v7 ASTs. ↓

fix Be aware of the `Import` vs `ImportExpression` distinction in this version range. If migrating to v2.0.0 or higher, adjust code to expect `ImportExpression`.

gotcha Prior to v2.0.0, `acorn-node` rejected escape sequences in `import.meta` which could lead to unexpected parsing errors for certain `import.meta` usages. ↓

fix Upgrade to v2.0.0 or higher to correctly handle escape sequences in `import.meta`. If unable to upgrade, avoid using escape sequences in `import.meta` properties.

breaking A regression in `import.meta` parsing was introduced and subsequently reverted. This could cause crashes or incorrect parsing of `import.meta` properties. ↓

fix Avoid `acorn-node` version 1.8.1. Upgrade to 1.8.2 or later, or downgrade to 1.8.0.

Install

npm install acorn-node

yarn add acorn-node

pnpm add acorn-node

Imports

acorn
wrong
```
const acorn = require('acorn')
```
correct
```
import * as acorn from 'acorn-node'
```
The primary export is the configured Acorn parser. While CommonJS `require('acorn-node')` is also common, using `import * as acorn from 'acorn-node'` is standard for ESM contexts.
walk
wrong
```
const { walk } = require('acorn-node')
```
correct
```
import { simple as walkSimple } from 'acorn-node/walk'
```
The AST walker is available from a sub-path. It exposes various walking methods (e.g., `simple`, `full`, `ancestor`) rather than a single `walk` function.
NodeTypes
wrong
```
import { Import } from 'acorn-node'
```
correct
```
import { Node } from 'acorn-node'
```
Node types are implicitly part of the AST. Specifically, dynamic import nodes changed from `Import` to `ImportExpression` in v2.0.0, aligning with Acorn's standard AST.

Quickstart

This example demonstrates parsing a JavaScript code snippet using acorn-node, including modern features like private class fields, static class fields, numeric separators, BigInts, dynamic `import()`, and `export * as ns from`. It then uses the bundled `walk` utility to traverse the AST and identify specific node types.

import * as acorn from 'acorn-node';
import { simple as walkSimple } from 'acorn-node/walk';

const code = `
  class MyClass {
    #privateField = 1;
    static publicStaticField = 2;
    constructor() {
      console.log(this.#privateField);
    }
  }
  const bigNum = 1_000_000_000_000_000n;
  const dynamicImport = import('./module.js');
  export * as ns from './ns.mjs';
`;

try {
  const ast = acorn.parse(code, { sourceType: 'module' });
  console.log('AST parsed successfully. Root node type:', ast.type);

  let foundClassFields = 0;
  walkSimple(ast, {
    PropertyDefinition(node) {
      if (node.key.type === 'PrivateIdentifier' || node.static) {
        foundClassFields++;
      }
    },
    ImportExpression(node) {
      console.log('Found dynamic import:', node.source.value);
    }
  });
  console.log(`Found ${foundClassFields} class field definitions.`);

} catch (e) {
  console.error('Parsing error:', e.message);
}