hast-util-to-jsx-runtime

hast-util-to-jsx-runtime

hast utility to transform a tree to preact, react, solid, svelte, vue, etc., with an automatic JSX runtime.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • toJsxRuntime(tree, options)
  • Options
  • Components
  • ElementAttributeNameCase
  • Fragment
  • Jsx
  • JsxDev
  • Props
  • Source
  • Space
  • StylePropertyNameCase
• Examples
  • Example: Preact
  • Example: Vue
  • Example: Solid
  • Example: Svelte
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a utility that takes a hast tree and an automatic JSX runtime and turns the tree into anything you whish.

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. In Node.js (version 14.14+ and 16.0+), install with npm:

npm install hast-util-to-jsx-runtime

In Deno with esm.sh:

import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@1'

In browsers with esm.sh:

<script type="module">
  import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@1?bundle'
</script>

Use

import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
import {renderToStaticMarkup} from 'react-dom/server'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'

const tree = h('h1', 'Hello, world!')

const doc = renderToStaticMarkup(toJsxRuntime(tree, {Fragment, jsx, jsxs}))

console.log(doc)

Yields:

<h1>Hello, world!</h1>

API

This package exports the identifier toJsxRuntime. There is no default export.

toJsxRuntime(tree, options)

Transform a hast tree to preact, react, solid, svelte, vue, etc., with an automatic JSX runtime.

Parameters

• tree (Node) — tree to transform
• options (Options, required) — configuration

Returns

Result from your configured JSX runtime (JSX.Element).

Options

Configuration (TypeScript type).

Fields

• Fragment (Fragment, required) — fragment
• jsx (Jsx, required in production) — dynamic JSX
• jsxs (Jsx, required in production) — static JSX
• jsxDEV (JsxDev, required in development) — development JSX
• development (boolean, default: false) — whether to use jsxDEV when on or jsx and jsxs when off
• components (Partial<Components>, optional) — components to use
• elementAttributeNameCase (ElementAttributeNameCase, 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, default: 'html') — whether tree is in the 'html' or 'svg' space, when an <svg> 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, default: 'dom') — specify casing to use for property names in style objects

Components

Possible components to use (TypeScript type).

Each key is a tag name typed in JSX.IntrinsicElements. 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

import type {Element} from 'hast'

type Components = {
  [TagName in keyof JSX.IntrinsicElements]:
    | Component<JSX.IntrinsicElements[TagName] & ExtraProps>
    | keyof JSX.IntrinsicElements
}

type ExtraProps = {node?: Element | undefined}

type Component<ComponentProps> =
  // Function component:
  | ((props: ComponentProps) => JSX.Element | string | null | undefined)
  // Class component:
  | (new (props: ComponentProps) => JSX.ElementClass)

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

type ElementAttributeNameCase = 'react' | 'html'

Fragment

Represent the children, typically a symbol (TypeScript type).

Type

type Fragment = unknown

Jsx

Create a production element (TypeScript type).

Parameters

• type (unknown) — element type: Fragment symbol, tag name (string), component
• props (Props) — element props, children, and maybe node
• key (string or undefined) — dynamicly generated key to use

Returns

An element from your framework (JSX.Element).

JsxDev

Create a development element (TypeScript type).

Parameters

• type (unknown) — element type: Fragment symbol, tag name (string), component
• props (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) — info about source
• self (undefined) — nothing (this is used by frameworks that have components, we don’t)

Returns

An element from your framework (JSX.Element).

Props

Properties and children (TypeScript type).

Type

import type {Element} from 'hast'

type Props = {
  [prop: string]:
    | Element // For `node`.
    | Array<JSX.Element | string | null | undefined> // For `children`.
    | Record<string, string> // For `style`.
    | string
    | number
    | boolean
    | undefined
  children: Array<JSX.Element | string | null | undefined> | undefined
  node?: Element | undefined
}

Source

Info about source (TypeScript type).

Fields

• fileName (string or undefined) — name of source file
• lineNumber (number or undefined) — line where thing starts (1-indexed)
• columnNumber (number or undefined) — column where thing starts (0-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

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

type StylePropertyNameCase = 'dom' | 'css'

Examples

Example: Preact

👉 Note: you must set elementAttributeNameCase: 'html' for preact.

In Node.js, do:

import {Fragment, jsx, jsxs} from 'preact/jsx-runtime'
import {render} from 'preact-render-to-string'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'

const result = render(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  })
)

console.log(result)

Yields:

<h1>hi!</h1>

In a browser, do:

import {Fragment, jsx, jsxs} from 'https://esm.sh/preact@10/jsx-runtime'
import {render} from 'https://esm.sh/preact@10'
import {h} from 'https://esm.sh/hastscript@7'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@1'

render(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  }),
  document.getElementById('root')
)

Example: Vue

👉 Note: you must set elementAttributeNameCase: 'html' for Vue.

In Node.js, do:

import {Fragment, jsx, jsxs} from 'vue-jsx-runtime/jsx-runtime'
import serverRenderer from '@vue/server-renderer'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'

console.log(
  await serverRenderer.renderToString(
    toJsxRuntime(h('h1', 'hi!'), {
      Fragment,
      jsx,
      jsxs,
      elementAttributeNameCase: 'html'
    })
  )
)

Yields:

<h1>hi!</h1>

In a browser, do:

import {createApp} from 'https://esm.sh/vue@3'
import {Fragment, jsx, jsxs} from 'https://esm.sh/vue-jsx-runtime@0.1/jsx-runtime'
import {h} from 'https://esm.sh/hastscript@7'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@1'

createApp(Component).mount('#root')

function Component() {
  return toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  })
}

Example: Solid

👉 Note: you must set elementAttributeNameCase: 'html' and stylePropertyNameCase: 'css' for Solid.

In Node.js, do:

import {Fragment, jsx, jsxs} from 'solid-jsx/jsx-runtime'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'

console.log(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html',
    stylePropertyNameCase: 'css'
  }).t
)

Yields:

<h1 >hi!</h1>

In a browser, do:

import {Fragment, jsx, jsxs} from 'https://esm.sh/solid-js@1/h/jsx-runtime'
import {render} from 'https://esm.sh/solid-js@1/web'
import {h} from 'https://esm.sh/hastscript@7'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@1'

render(Component, document.getElementById('root'))

function Component() {
  return toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html',
    stylePropertyNameCase: 'css'
  })
}

Example: Svelte

I have no clue how to render a Svelte component in Node, but you can get that component with:

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:

[class Component extends SvelteComponent]

Syntax

HTML is parsed according to WHATWG HTML (the living standard), which is also followed by browsers such as Chrome, Firefox, and Safari.

Types

This package is fully typed with TypeScript. It exports the additional types Components, ElementAttributeNameCase, Fragment, Jsx, JsxDev, Options, Props, Source, Space, and StylePropertyNameCase.

The function toJsxRuntime returns a JSX.Element, which means that the JSX namespace has to by typed. Typically this is done by installing your frameworks types (e.g., @types/react), which you likely already have.

Compatibility

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

Security

Be careful with user input in your hast tree. Use hast-util-santize to make hast trees safe.

Related

• hastscript — build hast trees
• hast-util-to-html — serialize hast as HTML
• hast-util-sanitize — sanitize hast

Contribute

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.

License

MIT © Titus Wormer