hyp

hyperons

🔥 The fastest JSX to string renderer on the server and in the browser.

Showing:

Popularity

Downloads/wk

90

GitHub Stars

27

Maintenance

Last Commit

2d ago

Contributors

7

Package

Dependencies

0

Size (min+gzip)

1.6KB

License

MIT

Type Definitions

Tree-Shakeable

Yes?

Categories

Readme

Hyperons

GitHub license Build Status Coverage Status npm version

Renders JSX components to static HTML on the server and in the browser.

Installation

This is a Node.js module available through the npm registry. Before installing, download and install Node.js. Node.js 8 or higher is required.

Installation is done using the npm install command:

$ npm install -S hyperons

Features

  • Share code between React single-page apps and plain HTML pages
  • Render components on the server and in the browser
  • Superfast and tiny code size (1.2kb gzipped)
  • Support for CSS stringification, boolean attributes, void elements, fragments, and more
  • Render class components and functional components

Usage

This module provides two functions; one to create elements and one to render them. If you've worked with React or React-like libraries before then they're the equivalent to React.createElement() and ReactDOM.renderToString().

The example below shows how to render a simple component using Hyperons:

import { h, render } from 'hyperons'

const Welcome = () => (
  h('div', { class: 'welcome-banner' },
    h('h1', null, 'Hello World!'),
    h('p', null, 'This component was rendered with Hyperons'))
)

render(Welcome())

Although you can use Hyperons without a compilation step, I'd recommend using JSX to more succinctly describe your markup. Here is the same component as before but rewritten to use JSX syntax:

import { h, render } from 'hyperons'

const Welcome = () => (
  <div class="welcome-banner">
    <h1>Hyperons</h1>
    <p>This component was rendered with Hyperons</p>
  </div>
)

render(<Welcome />)

Please Note that the JSX syntax will need to be transformed to regular JavaScript. If you do not wish to implement a build step for your server-side code I recommend using Sucrase which can enable on-the-fly transformations for .jsx files.

API

Hyperons.h() / Hyperons.createElement()

Hyperons.h(type[, props][, ...children])

Returns an element with the given props. It accepts the following arguments:

  • type The type of element to create which can be the name of an HTML element (such as "div"), a component, or a fragment.
  • props An object containing data to pass to a component or HTML attributes to render. See the props documentation for more information.
  • ...children Any number of child elements which may be simple values or other elements. See the children documentation for more information.

Hyperons.render() / Hyperons.renderToString()

Hyperons.render(element)

Returns the rendered element as a string. It accepts the following arguments:

  • element An element created with Hyperons.h()

Hyperons.Component

Components can be defined as classes or functions. Components written as classes should extend Hyperons.Component:

class Welcome extends Hyperons.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

The only method you must define for a class component is render(). See the component syntax documentation for more information.

Hyperons.Fragment

A Fragment is a special component which enables multiple elements to be rendered without a wrapper. See the using fragments documentation for more information.

<dl>
  {props.definitions.map((item) => (
    <Hyperons.Fragment>
      <dt>{item.title}</dt>
      <dd>{item.description}</dd>
    </Hyperons.Fragment>
  ))}
</dl>

Syntax

Components

Components are reusable pieces of UI which can be composed in useful ways. There are two types of components supported by Hyperons:

  • Class components, which are ES6 classes extending Hyperons.Component and have a render() method which returns elements.
  • Functional components which are functions that accept props and return elements.

Here is an example showing the same component written using a class and as a function:

// Class component
class SubmitButton extends Hyperons.Component {
  render() {
    return (
      <button type="submit">{this.props.text}</button>
    )
  }
}

// Functional component
const SubmitButton = (props) => (
  <button type="submit">{props.text}</button>
)

When using React or React-like libraries class components are usually used to add extra functionality such as hooking into lifecycle methods and maintain state. Hyperons renders static HTML so there is no state nor lifecycle methods.

Props

Props are objects either containing data to share with components or HTML attributes for a HTML element. A component should never modify the props it receives.

// Pass data to a component as props
h(SubmitButton, { text: 'Submit' })

// Render props as HTML attributes
h('button', { type: 'submit' })

Default prop values can be defined on component or functional components by adding a defaultProps property. These will be combined with any props received by the component:

// Class component
class SubmitButton extends Component {
  // ...

  static get defaultProps() {
    return {
      text: 'Submit'
    }
  }
}

// Functional component
const SubmitButton = (props) => {
  // ...
}

SubmitButton.defaultProps = {
  text: 'Submit'
}

HTML Attributes

When props are used to render attributes some property names and values will be treated differently by Hyperons:

  • Because class and for are reserved words in JavaScript you may use the aliases className and htmlFor instead.

  • Boolean attributes, such as hidden or checked, will only be rendered if assigned a truthy value.

  • Enumerated attributes which accept the values "true" or "false", such as contenteditable, will be rendered with their assigned value.

  • Any attributes requiring hyphens, such as aria-* and data-* should be written with hyphens.

  • Framework specific props such as key and ref will not be rendered.

Styles

The style attribute accepts a JavaScript object containing CSS properties and values.

CSS Properties may be written in camelCase for consistency with accessing the properties with JavaScript in the browser (e.g. element.style.marginBottom). Vendor prefixes other than ms should always begin with a capital letter (e.g. WebkitHyphens).

Hyperons will automatically append a px suffix to number values but certain properties will remain unitless (e.g. z-index and order). If you want to use units other than px, you should specify the value as a string with the desired unit. For example:

// Input:
const styles = {
  display: 'flex',
  order: 2,
  width: '50%',
  marginBottom: 20,
  WebkitHyphens: 'auto',
}

<div style={styles}></div>

// Output:
<div style="display:flex;order:2;width:50%;margin-bottom:20px;-webkit-hyphens:auto;></div>

HTML entities

Hyperons will escape all string values so if you need to output a HTML entity you can run into issues with double escaping. The simplest way to work-around this issue is to write the unicode character directly in your code (and use UTF-8 encoding for you source files). Otherwise, you can find the unicode number for the required character. For example:

// Incorrect. Outputs: <h1>Mac &amp;amp; Cheese</h1>
<h1>Mac &amp; Cheese</h1>
// Correct. Outputs: <h1>Mac &amp; Cheese</h1>
<h1>Mac & Cheese</h1>
// Correct. Outputs: <h1>Mac &amp; Cheese</h1>
<h1>{`Mac ${String.fromCharCode(38)} Cheese`}</h1>

Inner HTML

Hyperons supports the dangerouslySetInnerHTML property to inject unescaped HTML code. This is potentially dangerous and should never be used around any user input, but it can be useful as a last resort.

const html = { __html: '<i>Mac &amp; Cheese</i>' }
<div dangerouslySetInnerHTML={html}></div> // Outputs: <div><i>Mac &amp; Cheese</i></div>

Children

Components can render any number of child elements. Children can be strings, numbers, or other components. Components will receive references to any children via a children prop which enables components to be composed in useful ways.

const Wrapper = (props) => <p>{props.children}</p>
const html = <Wrapper>Hello</Wrapper> // Outputs: <p>Hello</p>

Please note that child elements will not be rendered for void elements.

Fragments

In React and React-like frameworks components must always return a single enclosing element. But sometimes it is required to return a list of elements, either because you don't need the extra elements or the extra elements would create invalid HTML output. For example, when rendering a description list the title and detail (<dt> and <dd>) elements are usually grouped in pairs:

function DescriptionList(props) {
  return (
    <dl>
      {props.definitions.map((item) => (
        <dt>{item.title}</dt>
        <dd>{item.description}</dd>
      ))}
    </dl>
  )
}

However, several tools will throw an error when evaluating the code above because the title and description elements are not wrapped in an enclosing element but wrapping them with an element would result in invalid HTML.

To solve this React 16.2 introduced the concept of fragments which enable a list of elements to be wrapped with an enclosing element without rendering anything extra. To use fragments in your JSX code Hyperons provides a special Fragment component:

function DescriptionList(props) {
  return (
    <dl>
      {props.definitions.map((item) => (
        <Hyperons.Fragment>
          <dt>{item.title}</dt>
          <dd>{item.description}</dd>
        </Hyperons.Fragment>
      ))}
    </dl>
  )
}

JSX

Not familiar with JSX? Check out WTF is JSX and JSX in Depth first.

If you're authoring your components with JSX syntax you will need to transpile your code into plain JavaScript in order to run them. Depending on the toolchain you're using there will be different plugins available. Some popular tools to transpile JavaScript are Babel (with the JSX plugin), Bublé (with JSX enabled) and Sucrase.

Project information

Development

The source code for this module is written in ES6 code and bundled for distribution using Rollup. Tests are written using Mocha as the test runner and Chai for assertions. Tests are run in both a Node.js environment and in a browser using Puppeteer.

Benchmarks

This repository contains benchmarking and profiling tools in the /benchmark directory. The current results for server-side rendering are below:

Benchmark run on Sat  2 May 2020 10:57:27 BST with Node v12.16.0

Using:
 - hyperapp@2.0.4
 - hyperons@1.0.0-beta.2
 - inferno@7.4.2
 - nervjs@1.5.6
 - preact@10.4.1
 - rax@1.1.1
 - react@16.13.1
 - vdo@4.2.0

Results:
 - Hyperapp x 6,845 ops/sec ±1.99% (88 runs sampled)
 - Hyperons x 11,377 ops/sec ±0.65% (94 runs sampled)
 - Inferno x 9,020 ops/sec ±0.76% (93 runs sampled)
 - Nerv x 5,343 ops/sec ±0.70% (94 runs sampled)
 - Preact x 3,560 ops/sec ±1.57% (95 runs sampled)
 - Rax x 5,805 ops/sec ±1.15% (92 runs sampled)
 - React x 4,609 ops/sec ±0.74% (94 runs sampled)
 - vdo x 6,608 ops/sec ±0.73% (93 runs sampled)

The fastest is: [ 'Hyperons' ]

Name

In particle physics, a hyperon is any baryon containing one or more strange quarks, but no charm

Wikipedia

In keeping with React and the wider ecosystem I wanted to give this project a science-related name but also something that implies being small and light. Thus, Hyperons.

Prior art

This module was originally inspired by the vhtml package and also borrows from a few other JSX to string implementations:

License

Hyperons is MIT licensed.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
Thurston TyeUK7 Ratings0 Reviews
Ex @Financial-Times
10 months ago