Acorn JavaScript Parser

Common errors

• SyntaxError: Unexpected token

  cause Parsing modern JavaScript syntax (e.g., `await` outside async, private class fields, nullish coalescing) with an outdated `ecmaVersion` or incorrect `sourceType` option.
  fix Adjust the `ecmaVersion` option to a sufficiently high year (e.g., `2022` or `'latest'`) and set `sourceType: 'module'` if parsing ES modules, or add appropriate plugins for non-standard syntax.

• TypeError: acorn.parse is not a function

  cause Attempting to use `acorn.parse` directly after an incorrect `import acorn from 'acorn'` (default import) in an ESM context, or an incorrect destructuring of the CommonJS export.
  fix Use `import * as acorn from 'acorn'` for ESM or `const acorn = require('acorn')` for CommonJS, then access `acorn.parse`.

• SyntaxError: 'return' outside of function

  cause A `return` statement is present at the top-level of the parsed code, which is disallowed by default.
  fix Set the `allowReturnOutsideFunction: true` option in the parser configuration to permit top-level return statements.

• SyntaxError: 'import' and 'export' may only appear at the top level

  cause `import` or `export` declarations are used inside a block or non-top-level scope, which is typically disallowed by the ECMAScript specification.
  fix Set the `allowImportExportEverywhere: true` option in the parser configuration. Note that this might deviate from strict spec compliance.

Warnings

• breaking The `ecmaVersion` option is now explicitly required for `acorn.parse()`. While omitting it might currently work with a warning, it will cause an error in future versions.
  Fix: Always provide the `ecmaVersion` option (e.g., `{ ecmaVersion: 2022 }` or `{ ecmaVersion: 'latest' }`).
• breaking The `ecmaVersion` option in v8 and later prefers year-based numbers (e.g., `2020`) over plain version numbers (e.g., `11`), although older numbers are still supported for backward compatibility. The default `ecmaVersion` also changed to 9 (ES2018) in v7.0.0.
  Fix: Update `ecmaVersion` to use year-based numbers like `2022` or the string `'latest'` for modern JavaScript parsing.
• breaking The `acorn.version` property was removed in favor of accessing the version via `pkg.version`. Code directly referencing `acorn.version` will break.
  Fix: Retrieve the package version using `require('acorn/package.json').version` in CommonJS or `import { version } from 'acorn/package.json'` in ESM.
• gotcha Acorn only implements 'stage 4' (finalized) ECMAScript features. Experimental or 'stage 3' proposals are not natively supported and require specific Acorn plugins (e.g., `acorn-jsx`, `acorn-bigint`).
  Fix: For parsing experimental syntax, identify and integrate the appropriate Acorn plugin using the `Parser.extend()` method.
• gotcha The default behavior for `allowReserved` (allowing reserved words as identifiers) changes based on `ecmaVersion`. It defaults to `true` for `ecmaVersion` 3 but `false` for higher versions, which can lead to parsing errors for older codebases expecting `allowReserved: true`.
  Fix: Explicitly set `allowReserved: true` in options if parsing older JavaScript code that uses reserved words as identifiers with a modern `ecmaVersion`.
• gotcha Using `sourceType: 'commonjs'` is not allowed when `allowAwaitOutsideFunction: true`, as top-level await is a module feature.
  Fix: Ensure `sourceType` is set to `'module'` when `allowAwaitOutsideFunction` is enabled for top-level `await` expressions.

Install

• npm install acorn npm
• yarn add acorn yarn
• pnpm add acorn pnpm

Imports

• acorn
  wrong:

  import acorn from 'acorn'

  correct:

  import * as acorn from 'acorn'

  Acorn exports its API as a namespace object; a default import is incorrect. This is the preferred ESM import.
• acorn
  wrong:

  const { parse } = require('acorn')

  correct:

  const acorn = require('acorn')

  For CommonJS, `require('acorn')` returns the full API object. Destructuring directly may miss other top-level exports if not careful.
• Parser
  wrong:

  import { default as Parser } from 'acorn'

  correct:

  import { Parser } from 'acorn'

  The `Parser` class is a named export, primarily used for extending Acorn with plugins.

Quickstart

This quickstart demonstrates parsing a JavaScript code snippet using Acorn, specifying ECMAScript version and source type, and then logging the generated AST and handling potential syntax errors.

import { parse } from 'acorn';

const code = `
  function greet(name = 'World') {
    console.log(`Hello, ${name}!`);
  }
  greet('Registry');
  greet();
`;

try {
  const ast = parse(code, {
    ecmaVersion: 2022, // Specify the ECMAScript version
    sourceType: 'module', // Or 'script', or 'commonjs'
    locations: true, // Attach line/column location info to nodes
  });
  console.log('AST generated successfully:');
  console.log(JSON.stringify(ast, null, 2));

  // Example of accessing a node
  if (ast.body[0].type === 'FunctionDeclaration') {
    console.log(`\nFirst function name: ${ast.body[0].id.name}`);
  }
} catch (error) {
  console.error('Parsing error:', error.message);
  console.error('Position:', error.pos, 'Line:', error.loc.line, 'Column:', error.loc.column);
}