https://github.com/syntax-tree/hast-util-to-jsx-runtime
hast utility to transform to preact, react, solid, svelte, vue, etc
https://github.com/syntax-tree/hast-util-to-jsx-runtime
hast hast-util jsx preact react runtime solid svelte vue
Last synced: 28 days ago
JSON representation
hast utility to transform to preact, react, solid, svelte, vue, etc
- Host: GitHub
- URL: https://github.com/syntax-tree/hast-util-to-jsx-runtime
- Owner: syntax-tree
- License: mit
- Created: 2023-01-14T16:59:44.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-04T11:52:15.000Z (about 1 year ago)
- Last Synced: 2024-05-05T04:03:44.403Z (about 1 year ago)
- Topics: hast, hast-util, jsx, preact, react, runtime, solid, svelte, vue
- Language: JavaScript
- Homepage: https://unifiedjs.com
- Size: 143 KB
- Stars: 39
- Watchers: 8
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome-syntax-tree - hast-util-to-jsx-runtime - Transform to preact, react, solid, svelte, vue, etc. (hast utilities)
README
# hast-util-to-jsx-runtime
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
hast utility to transform a tree to
preact, react, solid, svelte, vue, etcetera,
with an automatic JSX runtime.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`toJsxRuntime(tree, options)`](#tojsxruntimetree-options)
* [`Components`](#components)
* [`CreateEvaluater`](#createevaluater)
* [`ElementAttributeNameCase`](#elementattributenamecase)
* [`EvaluateExpression`](#evaluateexpression)
* [`EvaluateProgram`](#evaluateprogram)
* [`Evaluater`](#evaluater)
* [`ExtraProps`](#extraprops)
* [`Fragment`](#fragment)
* [`Jsx`](#jsx)
* [`JsxDev`](#jsxdev)
* [`Options`](#options)
* [`Props`](#props)
* [`Source`](#source)
* [`Space`](#space)
* [`StylePropertyNameCase`](#stylepropertynamecase)
* [Errors](#errors)
* [Examples](#examples)
* [Example: Preact](#example-preact)
* [Example: Solid](#example-solid)
* [Example: Svelte](#example-svelte)
* [Example: Vue](#example-vue)
* [Syntax](#syntax)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)
## What is this?
This package is a utility that takes a [hast][github-hast] tree and an
[automatic JSX runtime][reactjs-jsx-runtime] and turns the tree into anything
you wish.
## When should I use this?
You can use this package when you have a hast syntax tree and want to use it
with whatever framework.
This package uses an automatic JSX runtime,
which is a sort of lingua franca for frameworks to support JSX.
Notably,
automatic runtimes have support for passing extra information in development,
and have guaranteed support for fragments.
## Install
This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:
```sh
npm install hast-util-to-jsx-runtime
```
In Deno with [`esm.sh`][esmsh]:
```js
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
```
In browsers with [`esm.sh`][esmsh]:
```html
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2?bundle'
```
## Use
```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsxs, jsx} from 'react/jsx-runtime'
import {renderToStaticMarkup} from 'react-dom/server'
const tree = h('h1', 'Hello, world!')
const doc = renderToStaticMarkup(toJsxRuntime(tree, {Fragment, jsxs, jsx}))
console.log(doc)
```
Yields:
```html
Hello, world!
```
> **Note**:
> to add better type support,
> register a global JSX namespace:
>
> ```ts
> import type {JSX as Jsx} from 'react/jsx-runtime'
>
> declare global {
> namespace JSX {
> type ElementClass = Jsx.ElementClass
> type Element = Jsx.Element
> type IntrinsicElements = Jsx.IntrinsicElements
> }
> }
> ```
## API
This package exports the identifier [`toJsxRuntime`][api-to-jsx-runtime].
It exports the [TypeScript][] types
[`Components`][api-components],
[`CreateEvaluater`][api-create-evaluater],
[`ElementAttributeNameCase`][api-element-attribute-name-case],
[`EvaluateExpression`][api-evaluate-expression],
[`EvaluateProgram`][api-evaluate-program],
[`Evaluater`][api-evaluater],
[`ExtraProps`][api-extra-props],
[`Fragment`][api-fragment],
[`Jsx`][api-jsx],
[`JsxDev`][api-jsx-dev],
[`Options`][api-options],
[`Props`][api-props],
[`Source`][api-source],
[`Space`][api-Space],
and
[`StylePropertyNameCase`][api-style-property-name-case].
There is no default export.
### `toJsxRuntime(tree, options)`
Transform a hast tree to
preact, react, solid, svelte, vue, etcetera,
with an automatic JSX runtime.
##### Parameters
* `tree`
([`Node`][github-hast-nodes])
— tree to transform
* `options`
([`Options`][api-options], required)
— configuration
##### Returns
Result from your configured JSX runtime
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).
### `Components`
Possible components to use (TypeScript type).
Each key is a tag name typed in `JSX.IntrinsicElements`,
if defined.
Each value is either a different tag name
or a component accepting the corresponding props
(and an optional `node` prop if `passNode` is on).
You can access props at `JSX.IntrinsicElements`.
For example,
to find props for `a`,
use `JSX.IntrinsicElements['a']`.
###### Type
```ts
import type {Element} from 'hast'
type ExtraProps = {node?: Element | undefined}
type Components = {
[TagName in keyof JSX.IntrinsicElements]:
| Component
| keyof JSX.IntrinsicElements
}
type Component =
// Class component:
| (new (props: ComponentProps) => JSX.ElementClass)
// Function component:
| ((props: ComponentProps) => JSX.Element | string | null | undefined)
```
### `CreateEvaluater`
Create an evaluator that turns ESTree ASTs from embedded MDX into values
(TypeScript type).
###### Parameters
There are no parameters.
###### Returns
Evaluater ([`Evaluater`][api-evaluater]).
### `ElementAttributeNameCase`
Casing to use for attribute names (TypeScript type).
HTML casing is for example
`class`, `stroke-linecap`, `xml:lang`.
React casing is for example
`className`, `strokeLinecap`, `xmlLang`.
###### Type
```ts
type ElementAttributeNameCase = 'html' | 'react'
```
### `EvaluateExpression`
Turn an MDX expression into a value (TypeScript type).
###### Parameters
* `expression` (`Expression` from `@types/estree`)
— estree expression
###### Returns
Result of expression (`unknown`).
### `EvaluateProgram`
Turn an MDX program (export/import statements) into a value (TypeScript type).
###### Parameters
* `program` (`Program` from `@types/estree`)
— estree program
###### Returns
Result of program (`unknown`);
should likely be `undefined` as ESM changes the scope but doesn’t yield
something.
### `Evaluater`
Evaluator that turns ESTree ASTs from embedded MDX into values (TypeScript
type).
###### Fields
* `evaluateExpression` ([`EvaluateExpression`][api-evaluate-expression])
— evaluate an expression
* `evaluateProgram` ([`EvaluateProgram`][api-evaluate-program])
— evaluate a program
### `ExtraProps`
Extra fields we pass (TypeScript type).
###### Type
```ts
type ExtraProps = {node?: Element | undefined}
```
### `Fragment`
Represent the children,
typically a symbol (TypeScript type).
###### Type
```ts
type Fragment = unknown
```
### `Jsx`
Create a production element (TypeScript type).
###### Parameters
* `type` (`unknown`)
— element type:
`Fragment` symbol,
tag name (`string`),
component
* `props` ([`Props`][api-props])
— element props,
`children`,
and maybe `node`
* `key` (`string` or `undefined`)
— dynamicly generated key to use
###### Returns
Element from your framework
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).
### `JsxDev`
Create a development element (TypeScript type).
###### Parameters
* `type` (`unknown`)
— element type:
`Fragment` symbol,
tag name (`string`),
component
* `props` ([`Props`][api-props])
— element props,
`children`,
and maybe `node`
* `key` (`string` or `undefined`)
— dynamicly generated key to use
* `isStaticChildren` (`boolean`)
— whether two or more children are passed (in an array),
which is whether `jsxs` or `jsx` would be used
* `source` ([`Source`][api-source])
— info about source
* `self` (`undefined`)
— nothing (this is used by frameworks that have components,
we don’t)
###### Returns
Element from your framework
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).
### `Options`
Configuration (TypeScript type).
###### Fields
* `Fragment` ([`Fragment`][api-fragment], required)
— fragment
* `jsxDEV` ([`JsxDev`][api-jsx-dev], required in development)
— development JSX
* `jsxs` ([`Jsx`][api-jsx], required in production)
— static JSX
* `jsx` ([`Jsx`][api-jsx], required in production)
— dynamic JSX
* `components` ([`Partial`][api-components], optional)
— components to use
* `createEvaluater` ([`CreateEvaluater`][api-create-evaluater], optional)
— create an evaluator that turns ESTree ASTs into values
* `development` (`boolean`, default: `false`)
— whether to use `jsxDEV` when on or `jsx` and `jsxs` when off
* `elementAttributeNameCase`
([`ElementAttributeNameCase`][api-element-attribute-name-case],
default: `'react'`)
— specify casing to use for attribute names
* `filePath` (`string`, optional)
— file path to the original source file,
passed in source info to `jsxDEV` when using the automatic runtime with
`development: true`
* `passNode` (`boolean`, default: `false`)
— pass the hast element node to components
* `space` ([`Space`][api-space], default: `'html'`)
— whether `tree` is in the `'html'` or `'svg'` space, when an ``
element is found in the HTML space,
this package already automatically switches to and from the SVG space when
entering and exiting it
* `stylePropertyNameCase`
([`StylePropertyNameCase`][api-style-property-name-case],
default: `'dom'`)
— specify casing to use for property names in `style` objects
* `tableCellAlignToStyle`
(`boolean`, default: `true`)
— turn obsolete `align` props on `td` and `th` into CSS `style` props
### `Props`
Properties and children (TypeScript type).
###### Type
```ts
import type {Element} from 'hast'
type Props = {
[prop: string]:
| Array // For `children`.
| Record // For `style`.
| Element // For `node`.
| boolean
| number
| string
| undefined
children: Array | undefined
node?: Element | undefined
}
```
### `Source`
Info about source (TypeScript type).
###### Fields
* `columnNumber` (`number` or `undefined`)
— column where thing starts (0-indexed)
* `fileName` (`string` or `undefined`)
— name of source file
* `lineNumber` (`number` or `undefined`)
— line where thing starts (1-indexed)
### `Space`
Namespace (TypeScript type).
> 👉 **Note**:
> hast is not XML;
> it supports SVG as embedded in HTML;
> it does not support the features available in XML;
> passing SVG might break but fragments of modern SVG should be fine;
> use `xast` if you need to support SVG as XML.
###### Type
```ts
type Space = 'html' | 'svg'
```
### `StylePropertyNameCase`
Casing to use for property names in `style` objects (TypeScript type).
CSS casing is for example `background-color` and `-webkit-line-clamp`.
DOM casing is for example `backgroundColor` and `WebkitLineClamp`.
###### Type
```ts
type StylePropertyNameCase = 'css' | 'dom'
```
## Errors
The following errors are thrown:
###### ``Expected `Fragment` in options``
This error is thrown when either `options` is not passed at all or
when `options.Fragment` is `undefined`.
The automatic JSX runtime needs a symbol for a fragment to work.
To solve the error,
make sure you are passing the correct fragment symbol from your framework.
###### `` Expected `jsxDEV` in options when `development: true` ``
This error is thrown when `options.development` is turned on (`true`),
but when `options.jsxDEV` is not a function.
The automatic JSX runtime,
in development,
needs this function.
To solve the error,
make sure you are importing the correct runtime functions
(for example, `'react/jsx-dev-runtime'`),
and pass `jsxDEV`.
###### ``Expected `jsx` in production options``
###### ``Expected `jsxs` in production options``
These errors are thrown when `options.development` is *not* turned on
(`false` or not defined),
and when `options.jsx` or `options.jsxs` are not functions.
The automatic JSX runtime,
in production,
needs these functions.
To solve the error,
make sure you are importing the correct runtime functions
(for example, `'react/jsx-runtime'`),
and pass `jsx` and `jsxs`.
###### `` Cannot handle MDX estrees without `createEvaluater` ``
This error is thrown when MDX nodes are passed that represent JavaScript
programs or expressions.
Supporting JavaScript can be unsafe and requires a different project.
To support JavaScript,
pass a `createEvaluater` function in `options`.
###### ``Cannot parse `style` attribute``
This error is thrown when a `style` attribute is found on an element,
which cannot be parsed as CSS.
Most frameworks don’t accept `style` as a string,
so we need to parse it as CSS,
and pass it as an object.
But when broken CSS is used,
such as `style="color:red; /*"`,
we crash.
To solve the error,
make sure authors write valid CSS.
Alternatively,
pass `options.ignoreInvalidStyle: true` to swallow these errors.
## Examples
### Example: Preact
> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` for preact.
In Node.js,
do:
```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'preact/jsx-runtime'
import {render} from 'preact-render-to-string'
const result = render(
toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html'
})
)
console.log(result)
```
Yields:
```html
hi!
```
In a browser,
do:
```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {Fragment, jsx, jsxs} from 'https://esm.sh/preact@10/jsx-runtime'
import {render} from 'https://esm.sh/preact@10'
render(
toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html'
}),
document.getElementById('root')
)
```
To add better type support,
register a global JSX namespace:
```ts
import type {JSX as Jsx} from 'preact/jsx-runtime'
declare global {
namespace JSX {
type ElementClass = Jsx.ElementClass
type Element = Jsx.Element
type IntrinsicElements = Jsx.IntrinsicElements
}
}
```
### Example: Solid
> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` and
> `stylePropertyNameCase: 'css'` for Solid.
In Node.js,
do:
```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'solid-jsx/jsx-runtime'
console.log(
toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html',
stylePropertyNameCase: 'css'
}).t
)
```
Yields:
```html
hi!
```
In a browser,
do:
```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {Fragment, jsx, jsxs} from 'https://esm.sh/solid-js@1/h/jsx-runtime'
import {render} from 'https://esm.sh/solid-js@1/web'
render(Component, document.getElementById('root'))
function Component() {
return toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html',
stylePropertyNameCase: 'css'
})
}
```
To add better type support,
register a global JSX namespace:
```ts
import type {JSX as Jsx} from 'solid-js/jsx-runtime'
declare global {
namespace JSX {
type ElementClass = Jsx.ElementClass
type Element = Jsx.Element
type IntrinsicElements = Jsx.IntrinsicElements
}
}
```
### Example: Svelte
I have no clue how to render a Svelte component in Node,
but you can get that component with:
```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'svelte-jsx'
const svelteComponent = toJsxRuntime(h('h1', 'hi!'), {Fragment, jsx, jsxs})
console.log(svelteComponent)
```
Yields:
```text
[class Component extends SvelteComponent]
```
Types for Svelte are broken.
Raise it with Svelte.
### Example: Vue
> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` for Vue.
In Node.js,
do:
```js
import serverRenderer from '@vue/server-renderer'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'vue/jsx-runtime' // Available since `[email protected]`.
console.log(
await serverRenderer.renderToString(
toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html'
})
)
)
```
Yields:
```html
hi!
```
In a browser,
do:
```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {createApp} from 'https://esm.sh/vue@3'
import {Fragment, jsx, jsxs} from 'https://esm.sh/vue@3/jsx-runtime'
createApp(Component).mount('#root')
function Component() {
return toJsxRuntime(h('h1', 'hi!'), {
Fragment,
jsx,
jsxs,
elementAttributeNameCase: 'html'
})
}
```
To add better type support,
register a global JSX namespace:
```ts
import type {JSX as Jsx} from 'vue/jsx-runtime'
declare global {
namespace JSX {
type ElementClass = Jsx.ElementClass
type Element = Jsx.Element
type IntrinsicElements = Jsx.IntrinsicElements
}
}
```
## Syntax
HTML is parsed according to WHATWG HTML (the living standard),
which is also followed by browsers such as Chrome,
Firefox,
and Safari.
## 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,
`hast-util-to-jsx-runtime@2`,
compatible with Node.js 16.
## Security
Be careful with user input in your hast tree.
Use [`hast-util-santize`][github-hast-util-sanitize] to make hast trees safe.
## Related
* [`hastscript`](https://github.com/syntax-tree/hastscript)
— build hast trees
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
— serialize hast as HTML
* [`hast-util-sanitize`][github-hast-util-sanitize]
— sanitize hast
## Contribute
See [`contributing.md`][health-contributing]
in
[`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## License
[MIT][file-license] © [Titus Wormer][wooorm]
[api-components]: #components
[api-create-evaluater]: #createevaluater
[api-element-attribute-name-case]: #elementattributenamecase
[api-evaluate-expression]: #evaluateexpression
[api-evaluate-program]: #evaluateprogram
[api-evaluater]: #evaluater
[api-extra-props]: #extraprops
[api-fragment]: #fragment
[api-jsx]: #jsx
[api-jsx-dev]: #jsxdev
[api-options]: #options
[api-props]: #props
[api-source]: #source
[api-space]: #space
[api-style-property-name-case]: #stylepropertynamecase
[api-to-jsx-runtime]: #tojsxruntimetree-options
[badge-build-image]: https://github.com/syntax-tree/hast-util-to-jsx-runtime/workflows/main/badge.svg
[badge-build-url]: https://github.com/syntax-tree/hast-util-to-jsx-runtime/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-to-jsx-runtime.svg
[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-to-jsx-runtime
[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-to-jsx-runtime.svg
[badge-downloads-url]: https://www.npmjs.com/package/hast-util-to-jsx-runtime
[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-to-jsx-runtime
[badge-size-url]: https://bundlejs.com/?q=hast-util-to-jsx-runtime
[esmsh]: https://esm.sh
[file-license]: license
[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[github-hast]: https://github.com/syntax-tree/hast
[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes
[github-hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
[health]: https://github.com/syntax-tree/.github
[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md
[npmjs-install]: https://docs.npmjs.com/cli/install
[reactjs-jsx-runtime]: https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html
[typescript]: https://www.typescriptlang.org
[wooorm]: https://wooorm.com