Acorn with Node.js Syntax Plugins

Common errors

• 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).

• 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') { ... }`.

• 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 npm
• yarn add acorn-node yarn
• pnpm add acorn-node pnpm

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);
}