babel-plugin-htm

library3.0.0jsnpmunverified

A Babel plugin that compiles htm's tagged template literal syntax (html`...`) into hyperscript calls, React.createElement, Preact h, or plain VNode objects. Version 3.1.1 is current, with a slower release cadence after the major 3.0.0 rework. Unlike JSX, htm uses standard template literals, requiring no build-time syntax changes beyond this plugin. The plugin offers flexible pragma configuration, auto-import options, and experimental outputs like plain objects or monomorphic structures. It integrates with React, Preact, and any hyperscript library and supports features like static subtree caching since v3.

database aws devops data workflow

npm install babel-plugin-htm

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-HTM

babel-plugin-htm

databasejavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (plugin)

✓ module.exports = { plugins: [['htm', { pragma: 'h' }]] }

✗ Cannot import as ES module; babel plugins are CommonJS.

Babel plugins are loaded as CommonJS modules. In .babelrc or babel.config.js, use require or module.exports.

html

✓ import { html } from 'htm'

✗ import html from 'htm'

htm exports a named 'html' function, not default. For Preact, use 'htm/preact'.

html from htm/preact

✓ import { html } from 'htm/preact'

✗ import { html } from 'htm' (works but no Preact runtime)

htm/preact provides a preconfigured html function using Preact's h. For standalone, use 'htm/preact/standalone'.

Shows how to configure babel-plugin-htm with React pragma, use built-ins, fixed arity, and compile a tagged template component.

// babel.config.js module.exports = { plugins: [ ['htm', { pragma: 'React.createElement', tag: 'html', useBuiltIns: true, variableArity: false }] ] }; // src/App.jsx import { html } from 'htm/react'; function App(props) { return html`<div class="app"><h1>Hello, ${props.name}!</h1></div>`; } // Compiled output: // import React from 'react'; // import { html as _html } from 'htm/react'; // function App(props) { // return React.createElement("div", { class: "app" }, React.createElement("h1", null, "Hello, ", props.name, "!")); // }

Debug

Known issues

breakingIn v3.0.0, the plugin no longer automatically injects the htm import. You must use the 'import' option to auto-import, or manually import htm.

fix

Add 'import' option to plugin config or manually import htm in your source files.

affects: >=3.0.0 <3.0.0

deprecatedThe 'pragma' option default changed from 'h' to 'React.createElement'? No, default remains 'h' but it's recommended to set it explicitly.

fix

Set 'pragma' option explicitly to avoid confusion: e.g., `pragma: 'h'` for Preact.

affects: all

gotchaWhen using 'import' option with a string, the import is added only if the tag is used. If not used, no import is added, which can cause runtime errors if you expected it.

fix

Always ensure your code uses the tagged template with the specified tag, or manually import the pragma function.

affects: >=3.0.0

gotchaThe 'variableArity' option (default true) produces calls like h('div', null, 'text') . Setting to false produces h('div', null, ['text']). This changes children parameter type from rest args to array.

fix

Ensure your hyperscript function can handle both rest args and array children. With false, always pass children as array.

affects: all

gotchaSetting 'useNativeSpread' to true uses object spread syntax in output, which requires Babel's object spread plugin or preset-env with appropriate targets.

fix

Enable @babel/plugin-proposal-object-rest-spread or use preset-env with targets supporting object spread.

affects: all

Errors

Common errors & fixes

Error: Babel plugin 'htm' threw an error: Cannot find module 'htm'

The plugin expects the 'htm' package to be installed as a peer dependency.

fix

Install htm: npm install htm

Uncaught ReferenceError: h is not defined

The compiled output calls h() but no hyperscript function is imported or defined.

fix

Either import a hyperscript lib (e.g., import { h } from 'preact') and set pragma: 'h', or use 'import' option to auto-import.

SyntaxError: Unexpected template string (at ...) when using html`...` without plugin

The browser or Node does not natively understand tagged template literal usage for HTML generation.

fix

Ensure babel-plugin-htm is configured and Babel is transpiling the code, or use htm at runtime without compilation.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

htmoptionalProvides the runtime tagged template function (e.g., html) that babel-plugin-htm compiles; not required if only using the plugin for static compilation.

Agent activity

30 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/developit/htm ↗

packagehttps://www.npmjs.com/package/babel-plugin-htm ↗