Meriyah JavaScript Parser

Common errors

• SyntaxError: The 'import' keyword is not allowed in CommonJS modules.

  cause Attempting to parse ES module syntax (e.g., `import`, `export`) when Meriyah is configured for 'script' or 'commonjs' `sourceType`.
  fix Pass `{ sourceType: 'module' }` to the `parse` options: `parse(code, { sourceType: 'module' });`

• SyntaxError: Unexpected token '<'

  cause Parsing JSX syntax (e.g., `<div />`) without enabling the `jsx` option.
  fix Pass `{ jsx: true }` to the `parse` options: `parse(code, { jsx: true });`

• SyntaxError: Invalid regular expression: /(?<word>\w+)/d: Invalid group specifier name

  cause Meriyah uses the JavaScript runtime for RegExp validation, and the current Node.js version does not support a specific RegExp feature used in the parsed code.
  fix Update your Node.js environment to a version that supports the required RegExp features (e.g., Node.js >= 24). Alternatively, set `validateRegex: false` in the parse options to bypass runtime RegExp validation.

Warnings

• breaking As of v7.1.0, assigning to a `CallExpression` is now treated as a runtime error in Annex B (web compatibility) mode. This behavior change aligns with stricter ECMAScript specifications, potentially breaking code that previously relied on this pattern.
  Fix: Review code that assigns values directly to the result of function calls, especially in contexts where Annex B (webcompat) features are enabled. Refactor such code to avoid this pattern.
• gotcha Meriyah explicitly does NOT support TypeScript or Flow syntax. It is designed solely for parsing standard ECMAScript and select Stage 3 TC39 proposals.
  Fix: For projects requiring TypeScript or Flow parsing, consider alternative parsers like `@typescript-eslint/typescript-estree` or `babel-parser`.
• gotcha RegExp validation depends on the JavaScript runtime. Newer RegExp features (e.g., RegExp modifiers, duplicate named groups) may require Node.js >= 24. Parsing code with these features on older Node.js versions (or other runtimes) might lead to `SyntaxError` if `validateRegex: true` is enabled (the default).
  Fix: Update your Node.js environment to a version that supports the required RegExp features. Alternatively, set `validateRegex: false` in the parse options to bypass runtime RegExp validation, but be aware this may allow invalid RegExp to parse without error.
• breaking Meriyah requires Node.js version 20.0.0 or higher. Running Meriyah on older Node.js environments will result in errors.
  Fix: Ensure your project's Node.js version meets the `engines.node` requirement (>=20.0.0).
• gotcha Parsing code as an ES module, CommonJS module, or with JSX syntax requires explicit options. The default `sourceType` is 'script', and `jsx` is `false`.
  Fix: For ES modules, use `sourceType: 'module'`. For CommonJS, use `sourceType: 'commonjs'`. For JSX, enable `jsx: true` in the `parse` options.

Install

• npm install meriyah npm
• yarn add meriyah yarn
• pnpm add meriyah pnpm

Imports

• parse
  wrong:

  const { parse } = require('meriyah');

  correct:

  import { parse } from 'meriyah';

  Meriyah is primarily an ESM package. While bundlers or transpilers might enable `require`, direct CJS `require` might not work natively in modern Node.js environments without specific configurations.
• isParseError
  wrong:

  import isParseError from 'meriyah';

  correct:

  import { isParseError } from 'meriyah';

  This utility function, available since v7.1.0, is a named export useful for robustly checking if an error originated from Meriyah's parsing process.
• ParserOptions
  wrong:

  import { ParserOptions } from 'meriyah';

  correct:

  import type { ParserOptions } from 'meriyah';

  For TypeScript users, `ParserOptions` is a type definition and should be imported using `import type` to avoid runtime side effects or errors.

Quickstart

Demonstrates parsing a complex JavaScript module with various features, including ESNext proposals, web compatibility, location tracking, and error handling.

import { parse, isParseError } from 'meriyah';
import type { Program } from 'estree'; // Assuming ESTree types are needed for the result

const javascriptCode = `
  // This is a complex JavaScript module demonstrating various features.
  import { someUtil } from './utils.js';

  @debounce(300)
  class MyClass {
    #privateField = 42; // Private class field (ES2022)

    constructor(name) {
      this.name = name;
    }

    // A method with decorators (TC39 Stage 3, requires 'next' option)
    @log
    greet(param) {
      console.log(`Hello, ${this.name}! ${param}`);
      return someUtil(this.#privateField);
    }
  }

  export const instance = new MyClass('Meriyah User');

  // Example of Annex B feature (non-strict mode)
  // function foo() { 'use strict'; with (obj) {} } // This would error in strict mode
  
  // A regular expression with newer features (requires Node.js >= 24 for full validation)
  const regex = /(?<word>\w+)/d; 
  if ("test".match(regex)) {
    console.log("Matched!");
  }
`;

try {
  const ast: Program = parse(javascriptCode, {
    sourceType: 'module', // Parse as an ES module
    ranges: true,        // Include start/end offsets for each node
    loc: true,           // Include line/column location information
    next: true,          // Enable TC39 Stage 3 proposals (e.g., Decorators)
    jsx: false,          // Explicitly disable JSX (if not needed)
    webcompat: true,     // Enable web compatibility (Annex B)
    validateRegex: true, // Validate regular expressions with the current JS runtime
  });

  console.log('Successfully parsed AST:');
  // console.log(JSON.stringify(ast, null, 2)); // Uncomment to see the full AST
  console.log(`Program type: ${ast.type}`);
  console.log(`First statement type: ${ast.body[0].type}`);

} catch (e: any) {
  if (isParseError(e)) {
    console.error(`Meriyah Parse Error: ${e.message} at line ${e.loc?.line}, column ${e.loc?.column}`);
  } else {
    console.error('An unexpected error occurred:', e.message);
  }
}