A lean "template" engine for producing static hypertext documents (HTML) using JSX.

Supports structured class and style creation, context, form improvements, error handling, stable ID generation, and pretty printed results.

Zero dependencies, minimal source (less than 3KB minified and gzipped), and no reliance on a specific JavaScript version. Use it in any version of node, or any browser.

Getting started

1. Install this module

   npm install hyperjsx

2. Configure your JSX environment to use the hyperjsx transforms. For example, for TypeScript, include these two lines in your tsconfig.json

   "jsx": "react-jsx",
   "jsxImportSource": "hyperjsx",

API

render(root: JSX.Element, options?: Options): string

Given a JSX element, render an HTML string.

Options:

• indent - A string to use as the indentation or false to disable pretty printed results (default " ").
• xml - Set to true to use XML serialization rules instead of HTML rules (default false).

stream(root: JSX.Element, options?: Options): NodeJS.ReadableStream

Given a JSX element, stream an HTML string.

Because this depends on a Node.js module, import this function from hyperjsx/stream.

createContext<T>(defaultValue: T): ContextComponent<T>

Creates a context component for use by useContext(). Context provides values which can be retrieved by any component within.

const ExampleContext = createContext('default value')

function useContext<T>(context: ContextComponent<T>): T

Get the current value of a context.

function TestUseContext() {
  const example = useContext(ExampleContext)
  return <div>{example}</div>
}

// '<div>test</div>'
render(
  <ExampleContext value="test">
    <TestUseContext />
  </ExampleContext>
)

useId(): string

Returns an opaque unique identifier stable to changes elsewhere. Useful if you need a "random" identifier

This value is stable, so multiple calls to useId() from the same component will return the same result. To get multiple unique values, append some identifer to the end.

function CustomForm() {
  const id = useId()
  return <>
    <input name={id+'-first'} />
    <input name={id+'-last'} />
  </>
}

The id value returned will use only alpha characters.

ErrorBoundary

A component which can catch an error thrown below it and replace the content with a fallback.

Props:

• fallback - any content or a Component (which may accept an error prop)
• onError - a function which is provided error (useful for logging)

Note: When streaming, a stream will wait until all content below an ErrorBoundary has completed before sending any bytes. As a result, placing an ErrorBoundary at the top level removes the ability to stream results entirely.

Et cetera

Hyperjsx also exports jsx (modern JSX transform), h (classic JSX transform, or manual hyperscript) and Fragment functions which can be used directly if necessary in leiu of or in additional to use of JSX directly.

Pretty printing

Hyperjsx pretty prints results. However it favors speed of rendering over idealized pretty results. More specifically, it has minimal lookaheads, so decisions about where to place line breaks need to be made before later content has been rendered. As a result some lines may be longer or shorter than you might expect from other pretty printing tools.