Getting started

Install the package:

npm install --save domstatejsx

Enabling JSX

domstatejsx ships a jsx-runtime compatible with automatic JSX transformation. If you are running a Vite project you have three options:

1. Use the Vite plugin

import domstatejsxPlugin from 'domstatejsx/vite-plugin';

export default {
  plugins: [domstatejsxPlugin()],
  // ...
};

2. Configure `esbuild` directly

export default {
  esbuild: {
    jsx: 'automatic',
    jsxImportSource: 'domstatejsx',
  },
  // ...
};

3. Use the classic runtime with pragmas

Include this in every .jsx file you want domstatejsx to take over:

import { createElement, Fragment } from 'domstatejsx';
/** @jsx createElement */
/** @jsxFrag Fragment */

Your first component

document.body.append(<h1>hello world</h1>);

JSX expressions return native DOM elements. The above is roughly equivalent to:

const element = document.createElement('h1');
element.textContent = 'hello world';
document.body.append(element);

Components are simply functions that return DOM elements:

function Counter() {
  return (
    <>
      <div>
        <button>Click me</button>
      </div>
      <div>
        Count: <span>0</span>
      </div>
    </>
  );
}

document.body.append(<Counter />);

<>...</> returns a native DocumentFragment. When inserted into the DOM, the fragment’s children are moved directly into the parent — the fragment itself disappears. A fragment-returning component like <Counter /> above spreads its children into whatever element contains it.

However, refs and context Providers cannot be attached to fragment-returning components — doing so throws an error at runtime. If you need to attach a ref or wrap a component in a Provider, have it return a single element instead:

// ❌ throws — cannot attach ref to a fragment-returning component
<Counter ref={myRef} />;

// ✅ wrap in an element
function Counter() {
  return <div>...</div>;
}