estree (and esast) utility to serialize estrees as JavaScript.

• What is this?
• When should I use this?
• Install
• Use
• API
  • toJs(tree[, options])
  • jsx
• Examples
  • Example: source maps
  • Example: comments
  • Example: JSX
• Types
• Compatibility
• Contribute
• License

This package is a utility that turns an estree syntax tree into a string of JavaScript.

You can use this utility when you want to get the serialized JavaScript that is represented by the syntax tree, either because you’re done with the syntax tree, or because you’re integrating with another tool that does not support syntax trees.

This utility is particularly useful when integrating with other unified tools, such as unist and vfile.

The utility esast-util-from-js does the inverse of this utility. It turns JS into esast.

This package is ESM only. In Node.js (version 14.14+, 16.0+, or 18.0+), install with npm:

npm install estree-util-to-js

In Deno with esm.sh:

import {toJs} from "https://esm.sh/estree-util-to-js@1"

In browsers with esm.sh:

<script type="module"> import {toJs} from "https://esm.sh/estree-util-to-js@1?bundle" </script>

import fs from 'node:fs/promises' import {parse} from 'acorn' import {toJs} from 'estree-util-to-js' const file = String(await fs.readFile('index.js')) const tree = parse(file, { ecmaVersion: 2022, sourceType: 'module', locations: true }) // @ts-expect-error: acorn is funky but it works fine. console.log(toJs(tree))

Yields:

{ value: "export {toJs} from './lib/index.js';\nexport {jsx} from './lib/jsx.js';\n", map: undefined }

This package exports the identifiers toJs and jsx. There is no default export.

Serialize an estree (Program) as JavaScript.

Configuration (optional).

Generate a source map by passing the SourceMapGenerator class from source-map in. This works if there is positional info on nodes.

Path to original input file (string, example: path/to/input.js). Only used in source map.

Object mapping node types to functions handling the corresponding nodes (Record<string, Handler>). Each Handler is passed the corresponding node and astrings internal state. See lib/jsx.js for examples.

An object with two fields:

• value (string) — serialized JavaScript
• map (Object?) — source map as (parsed) JSON, if SourceMapGenerator is passed

Map of handlers to handle the nodes of JSX extensions in JavaScript.

Source maps are supported when passing the SourceMapGenerator class from source-map. You should also pass filePath. Modified example from § Use above:

 import fs from 'node:fs/promises' import {parse} from 'acorn' +import {SourceMapGenerator} from 'source-map' import {toJs} from 'estree-util-to-js' -const file = String(await fs.readFile('index.js')) +const filePath = 'index.js' +const file = String(await fs.readFile(filePath)) const tree = parse(file, { ecmaVersion: 2022, @@ -11,4 +13,4 @@ const tree = parse(file, { }) // @ts-expect-error: acorn is funky but it works fine. -console.log(toJs(tree)) +console.log(toJs(tree, {filePath, SourceMapGenerator}))

Yields:

{ value: "export {toJs} from './lib/index.js';\nexport {jsx} from './lib/jsx.js';\n", map: { version: 3, sources: [ 'index.js' ], names: [], mappings: 'QAOQ,WAAW;QACX,UAAU', file: 'index.js' } }

To get comments to work, they have to be inside the tree. This is not done by Acorn. estree-util-attach-comments can do that. Modified example from § Use above:

 import fs from 'node:fs/promises' import {parse} from 'acorn' +import {attachComments} from 'estree-util-attach-comments' import {toJs} from 'estree-util-to-js' const file = String(await fs.readFile('index.js')) +/** @type {Array<import('estree-jsx').Comment>} */ +const comments = [] const tree = parse(file, { ecmaVersion: 2022, sourceType: 'module', - locations: true + locations: true, + // @ts-expect-error: acorn is funky these comments are fine. + onComment: comments }) +attachComments(tree, comments) // @ts-expect-error: acorn is funky but it works fine. console.log(toJs(tree))

Yields:

{ value: '/**\n' + "* @typedef {import('./lib/index.js').Options} Options\n" + "* @typedef {import('./lib/types.js').Handler} Handler\n" + "* @typedef {import('./lib/types.js').Handlers} Handlers\n" + "* @typedef {import('./lib/types.js').State} State\n" + '*/\n' + "export {toJs} from './lib/index.js';\n" + "export {jsx} from './lib/jsx.js';\n", map: undefined }

To get JSX to work, handlers need to be registered. This is not done by default, but they are exported as jsx and can be passed. Modified example from § Use above:

 import fs from 'node:fs/promises' -import {parse} from 'acorn' -import {toJs} from 'estree-util-to-js' +import {Parser} from 'acorn' +import acornJsx from 'acorn-jsx' +import {toJs, jsx} from 'estree-util-to-js' -const file = String(await fs.readFile('index.js')) +const file = '<>{1 + 1}</>' -const tree = parse(file, { +const tree = Parser.extend(acornJsx()).parse(file, { ecmaVersion: 2022, sourceType: 'module', locations: true }) // @ts-expect-error: acorn is funky but it works fine. -console.log(toJs(tree)) +console.log(toJs(tree, {handlers: jsx}))

Yields:

{ value: '<>{1 + 1}</>;\n', map: undefined }

This package is fully typed with TypeScript. It exports the additional types Options, Handler, Handlers, and State.

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

MIT © Titus Wormer