babel-plugin-htm

A Babel plugin that compiles htm syntax to hyperscript, React.createElement, or just plain objects.

Usage

In your Babel configuration (.babelrc, babel.config.js, "babel" field in package.json, etc), add the plugin:

1{
2  "plugins": [
3    ["htm", {
4      "pragma": "React.createElement"
5    }]
6  ]
7}

1// input:
2html`<div id="foo">hello ${you}</div>`
3
4// output:
5React.createElement("div", { id: "foo" }, "hello ", you)

options

pragma

The target "hyperscript" function to compile elements to (see Babel docs). Defaults to: "h".

tag=html

By default, babel-plugin-htm will process all Tagged Templates with a tag function named html. To use a different name, use the tag option in your Babel configuration:

1{"plugins":[
2  ["babel-plugin-htm", {
3    "tag": "myCustomHtmlFunction"
4  }]
5]}

import=false (experimental)

Auto-import the pragma function, off by default.

false (default)

Don't auto-import anything.

String

Import the pragma like import {<pragma>} from '<import>'.

With Babel config:

1"plugins": [
2  ["babel-plugin-htm", {
3    "tag": "$$html",
4    "import": "preact"
5  }]
6]

1import { html as $$html } from 'htm/preact';
2
3export default $$html`<div id="foo">hello ${you}</div>`

The above will produce files that look like:

1import { h } from 'preact';
2import { html as $$html } from 'htm/preact';
3
4export default h("div", { id: "foo" }, "hello ", you)

{module: String, export: String}

Import the pragma like import {<import.export> as <pragma>} from '<import.module>'.

With Babel config:

1"plugins": [
2  ["babel-plugin-htm", {
3    "pragma": "React.createElement",
4    "tag": "$$html",
5    "import": {
6      // the module to import:
7      "module": "react",
8      // a named export to use from that module:
9      "export": "default"
10    }
11  }]
12]

1import { html as $$html } from 'htm/react';
2
3export default $$html`<div id="foo">hello ${you}</div>`

The above will produce files that look like:

1import React from 'react';
2import { html as $$html } from 'htm/react';
3
4export default React.createElement("div", { id: "foo" }, "hello ", you)

useBuiltIns=false

babel-plugin-htm transforms prop spreads (<a ...${b}>) into Object.assign() calls. For browser support reasons, Babel's standard _extends helper is used by default. To use native Object.assign directly, pass {useBuiltIns:true}.

useNativeSpread=false

babel-plugin-htm transforms prop spreads (<a ...${b} x=y>) into { ...b, x: 'y' } object spread syntax. For browser support reasons, Babel's standard _extends helper is used by default. To use object spread syntax, pass {useNativeSpread:true}. This option takes precedence over the useBuiltIns option.

variableArity=true

By default, babel-plugin-htm transpiles to the same output as JSX would, which assumes a target function of the form h(type, props, ...children). If, for the purposes of optimization or simplification, you would like all calls to h() to be passed exactly 3 arguments, specify {variableArity:false} in your Babel config:

1html`<div />`  // h('div', null, [])
2html`<div a />`  // h('div', { a: true }, [])
3html`<div>b</div>`  // h('div', null, ['b'])
4html`<div a>b</div>`  // h('div', { a: true }, ['b'])

pragma=false (experimental)

Setting pragma to false changes the output to be plain objects instead of h() function calls:

1// input:
2html`<div id="foo">hello ${you}</div>`
3// output:
4{ tag:"div", props:{ id: "foo" }, children:["hello ", you] }

monomorphic (experimental)

Like pragma=false but converts all inline text to objects, resulting in the same object shape being used:

1// input:
2html`<div id="foo">hello ${you}</div>`
3// output:
4{ type: 1, tag:"div", props:{ id: "foo" }, text: null, children:[
5  { type: 3, tag: null, props: null, text: "hello ", children: null },
6  you
7] }