estree-util-build-jsx
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatestree utility to turn JSX into function calls:
<x />
-> h('x')
!Contents
* [`buildJsx(tree[, options])`](#buildjsxtree-options)
* [`Options`](#options)
* [`Runtime`](#runtime-1)
* [Example: use with Acorn](#example-use-with-acorn)
What is this?
This package is a utility that takes an estree (JavaScript) syntax tree as input that contains embedded JSX nodes (elements, fragments) and turns them into function calls.When should I use this?
If you already have a tree and only need to compile JSX away, use this. If you have code, use something like SWC or esbuild instead.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install estree-util-build-jsx
In Deno with
esm.sh
esmsh:import {buildJsx} from 'https://esm.sh/estree-util-build-jsx@3'
In browsers with
esm.sh
esmsh:<script type="module">
import {buildJsx} from 'https://esm.sh/estree-util-build-jsx@3?bundle'
</script>
Use
Say we have the followingexample.jsx
:import x from 'xastscript'
console.log(
<album id={123}>
<name>Born in the U.S.A.</name>
<artist>Bruce Springsteen</artist>
<releasedate date="1984-04-06">April 6, 1984</releasedate>
</album>
)
console.log(
<>
{1 + 1}
<self-closing />
<x name key="value" key={expression} {...spread} />
</>
)
…and next to it a module
example.js
:import fs from 'node:fs/promises'
import jsx from 'acorn-jsx'
import {fromJs} from 'esast-util-from-js'
import {buildJsx} from 'estree-util-build-jsx'
import {toJs} from 'estree-util-to-js'
const doc = String(await fs.readFile('example.jsx'))
const tree = fromJs(doc, {module: true, plugins: [jsx()]})
buildJsx(tree, {pragma: 'x', pragmaFrag: 'null'})
console.log(toJs(tree).value)
…now running
node example.js
yields:import x from "xastscript";
console.log(x("album", {
id: 123
}, x("name", null, "Born in the U.S.A."), x("artist", null, "Bruce Springsteen"), x("releasedate", {
date: "1984-04-06"
}, "April 6, 1984")));
console.log(x(null, null, 1 + 1, x("self-closing"), x("x", Object.assign({
name: true,
key: "value",
key: expression
}, spread))));
API
This package exports the identifierbuildJsx
api-build-jsx.
There is no default export.buildJsx(tree[, options])
Turn JSX in tree
into function calls: <x />
-> h('x')
!Algorithm
In almost all cases, this utility is the same as the Babel plugin, except that they work on slightly different syntax trees.Some differences:
- no pure annotations things
this
is not a component:<this>
->h('this')
, noth(this)
- namespaces are supported:
<a:b c:d>
->h('a:b', {'c:d': true})
,
which throws by default in Babel or can be turned on with `throwIfNamespace`
- no
useSpread
,useBuiltIns
, orfilter
options
Parameters
— tree to transform (typically [`Program`][program])
options
(Options
api-options, optional)
— configuration
Returns
Nothing (undefined
).Options
Configuration (TypeScript type).👉 Note: you can also configureruntime
,importSource
,pragma
, andpragmaFrag
from within files through comments.
Fields
runtime
Choose the runtimejsx-runtime (Runtime
api-runtime, default: 'classic'
).Comment form:
@jsxRuntime theRuntime
.importSource
Place to import jsx
, jsxs
, jsxDEV
, and Fragment
from, when the
effective runtime is automatic (string
, default: 'react'
).Comment form:
@jsxImportSource theSource
.👉 Note:/jsx-runtime
or/jsx-dev-runtime
is appended to this provided source. In CJS, that can resolve to a file (as intheSource/jsx-runtime.js
), but for ESM an export map needs to be set up to point to files:// … "exports": { // … "./jsx-runtime": "./path/to/jsx-runtime.js", "./jsx-dev-runtime": "./path/to/jsx-runtime.js" // …
pragma
Identifier or member expression to call when the effective runtime is classic
(string
, default: 'React.createElement'
).Comment form:
@jsx identifier
.pragmaFrag
Identifier or member expression to use as a symbol for fragments when the
effective runtime is classic (string
, default: 'React.Fragment'
).Comment form:
@jsxFrag identifier
.development
When in the automatic runtime, whether to import theSource/jsx-dev-runtime.js
,
use jsxDEV
, and pass location info when available (boolean
, default: false
).This helps debugging but adds a lot of code that you don’t want in production.
filePath
File path to the original source file (string
, example: 'path/to/file.js'
).
Passed in location info to jsxDEV
when using the automatic runtime with
development: true
.Runtime
How to transform JSX (TypeScript type).Type
type Runtime = 'automatic' | 'classic'
Examples
Example: use with Acorn
To support configuration from comments in Acorn, those comments have to be in the program. This is done byespree
espree but not automatically by acorn
acorn:import {Parser} from 'acorn'
import jsx from 'acorn-jsx'
const doc = '' // To do: get `doc` somehow.
const comments = []
const tree = Parser.extend(jsx()).parse(doc, {onComment: comments})
tree.comments = comments
Types
This package is fully typed with TypeScript. It exports the additional typeOptions
api-options and
Runtime
api-runtime.Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line,
estree-util-build-jsx@^3
,
compatible with Node.js 166.Related
— turn [hast](https://github.com/syntax-tree/hast) (HTML) to [estree][]
JSX
— turn [estree][] to Babel trees
Security
This package is safe.Contribute
Seecontributing.md
in syntax-tree/.github
contributing for ways to get
started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.