recma JavaScript Parser Plugin

1.0.0 · active · verified Sun Apr 19

recma-parse is a unified plugin for the recma ecosystem, designed to transform JavaScript source code into an Abstract Syntax Tree (AST). It leverages `esast-util-from-js` internally to parse JavaScript according to the ECMA-262 standard, producing ASTs in both esast and estree formats. As of its current stable version, 1.0.0, it is an ESM-only package, strictly requiring Node.js 16 or newer for execution. This package is part of the actively maintained `recma` monorepo, which provides a cohesive suite of tools for processing JavaScript ASTs, akin to how `remark` handles Markdown and `rehype` processes HTML. It differentiates itself by offering a robust, standards-compliant parsing step within the unified transformation pipeline, providing a foundational component for various JavaScript code transformations and analyses.

Common errors

```
SyntaxError: The requested module 'recma-parse' does not provide an export named 'recmaParse'
```
cause Attempting to import 'recmaParse' as a named export when 'recma-parse' only provides a default export.

fix Change the import statement to use the default import syntax: `import recmaParse from 'recma-parse'`.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/recma-parse/index.js from .../your-file.js not supported.
```
cause Trying to import `recma-parse` using CommonJS `require()` syntax in a CommonJS module, but `recma-parse` is an ESM-only package.

fix Convert your consuming module to an ES Module (e.g., by adding `"type": "module"` to your `package.json` or renaming the file to `.mjs`) and use `import recmaParse from 'recma-parse'`.

Warnings

breaking recma-parse is an ECMAScript Module (ESM) only package. It cannot be directly imported using CommonJS `require()` and requires a Node.js environment configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions).
Fix: Migrate your project to ESM imports or use dynamic `import()` for compatibility if absolutely necessary. Ensure your Node.js version is 16+.
gotcha As recma-parse processes JavaScript code, evaluating potentially unsafe or untrusted input through recma plugins can lead to security vulnerabilities. Always sanitize and validate any user-provided JavaScript code before processing it.
Fix: Never evaluate untrusted JavaScript code directly. Implement strict input validation and sanitization for any code passed to the parser or subsequent plugins.
breaking recma-parse@1 is compatible with Node.js 16 and newer. Future major releases will drop support for unmaintained Node.js versions, potentially requiring environment upgrades.
Fix: Ensure your project runs on a currently maintained version of Node.js (16+ for v1.x) to maintain compatibility and receive security updates.

Install

npm install recma-parse npm
yarn add recma-parse yarn
pnpm add recma-parse pnpm

Imports

recmaParse
wrong:
```
import { recmaParse } from 'recma-parse'
```
correct:
```
import recmaParse from 'recma-parse'
```
'recma-parse' provides a default export only; named imports will result in an error.
recmaParse
wrong:
```
const recmaParse = require('recma-parse')
```
correct:
```
import recmaParse from 'recma-parse'
```
'recma-parse' is an ESM-only package since v1.0.0 and does not support CommonJS 'require()' syntax.
Options
```
import type { Options } from 'recma-parse'
```
For TypeScript users to import the type definition for parser configuration options.

Quickstart

This example demonstrates how to set up a unified pipeline using recma-parse to parse JavaScript, transform JSX elements using recma-jsx and recma-build-jsx, and then serialize the modified AST back into JavaScript code using recma-stringify. It processes a simple JSX expression and outputs the equivalent React.createElement call.

import recmaBuildJsx from 'recma-build-jsx'
import recmaJsx from 'recma-jsx'
import recmaParse from 'recma-parse'
import recmaStringify from 'recma-stringify'
import { unified } from 'unified'

async function processJsx() {
  const file = await unified()
    .use(recmaParse)
    .use(recmaJsx)
    .use(recmaBuildJsx)
    .use(recmaStringify)
    .process('console.log(<em>Hi!</em>)')

  console.log(String(file))
}

processJsx()

view raw JSON →