High throughput React Server Side Rendering

For a simplified example of esx in action, check out esx-demo.

esx is designed to be a high speed SSR template engine for React.

It can be used with absolutely no code base changes.

Use it with a preloader flag like so:

node -r esx/experimental-optimize my-app.js

Note this is experimental, once stable this will become esx/optimize.

Alternatively babel-plugin-esx-ssr can be used to transpile for the same performance gains. The babel plugin would be a preferred option where speed of process initialization is important (such as serverless).

Optionally, esx is also a universal JSX-like syntax in plain JavaScript that allows for the elimination of transpilation in development environments.

• For the server side, using esx syntax will yield the same high speed results as the optimizing preloader
• For client side development, using esx syntax can enhance development workflow by removing the need for browser transpilation when developing in modern browsers
• For client side production esx can be compiled away for production with babel-plugin-esx-browser, resulting in zero-byte payload overhead.

It uses native Tagged Templates and works in all modern browsers.

Not only is this project on-going, it's also following a moving target (the React implementation).

This should only be used in production when:

• It has been verified to yield significant enough performance gains
• It has been thoroughly verified against your current implementation

esx needs use cases and battle testing. All issues are very welcome, PR's are extremely welcome and Collaborators are exceptionally, extraordinarily, exceedingly welcome.

If you or your team want support in integrating esx, or need help with server side rendering in general please feel free to contact me.

npm i esx

There are close to 3000 passing tests.

git clone https://github.com/esxjs/esx
cd esx
npm i
npm test
npm run test:client # test client-side implementation in node
npm tun test:browser # test client-side implementation in browser

Creating HTML with esx syntax is as close as possible to JSX:

• Spread props: <div ...${props}>
• Self-closing tags: <div />
• Attributes: <img src="https://example.com/img.png"/> and <img src=${src}/>
• Boolean attributes: <div draggable />
• Components: <Foo/>
  • Components must be registered with esx: esx.register({Foo})

• react v16.8+ is required as a peer dependency
• react-dom v16.8+ is required as a peer dependency
• esx is built for Node 10+
• Supported Operating Systems: Windows, Linux, macOS

esx should cover the API surface of all non-deprecated React features.

Notably, esx will not work with the Legacy Context API, but it will work with the New Context API.

While the legacy API is being phased out, there still may be modules in a projects depedency tree that rely on the legacy API. If you desperately need support for the legacy API, contact me..

Preload esx/optimize like so:

node -r esx/optimize my-app.js

That's it. This will convert all JSX and createElement calls to ESX format, unlocking the throughput benefits of SSR template rendering.

Additionally, esx can be written by hand for great ergonomic benefit in both server and client development contexts. Here's the example from the htm readme converted to esx (htm is discussed at the bottom of this readme):

// using require instead of import allows for no server transpilation
const { Component } = require('react') 
const esx = require('esx')()
class App extends Component {
  addTodo() {
    const { todos = [] } = this.state;
    this.setState({ todos: todos.concat(`Item ${todos.length}`) });
  }
  render({ page }, { todos = [] }) {
    return esx`
      <div class="app">
        <Header name="ToDo's (${page})" />
        <ul>
          ${todos.map(todo => esx`
            <li>${todo}</li>
          `)}
        </ul>
        <button onClick=${() => this.addTodo()}>Add Todo</button>
        <Footer>footer content here</Footer>
      </div>
    `
  }
}
const Header = ({ name }) => esx`<h1>${name} List</h1>`
const Footer = props => esx`<footer ...${props} />`

esx.register({ Header, Footer })

module.exports = App

In a client entry point this can be rendered the usual way:

const App = require('./App')
const container = document.getElementById('app')
const { hydrate } = require('react-dom') // using hydrate because we have SSR
const esx = require('esx')({ App })
hydrate(esx `<App page="All"/>`, container)

And the server entry point can use esx.renderToToString for high speed server-side rendering:

const { createServer } = require('http')
const App = require('./App')
createServer((req, res) => {
  res.end(`
    <html>
      <head><title>Todo</title></head>
      <body>
        <div id="app">
        ${esx.renderToString `<App page="All"/>`}
        </div>
      </body>
    </html>
  `)
}).listen(3000)

The esx module exports an initializer function, which returns a template string tag function.

The default export is a function that when called initializes an instance of esx.

import createEsx from 'esx'

const createEsx = require('esx')

The initializer takes an object of component mappings which it then uses to look up component references within the template.

When called, the Initializer returns a Template Engine instance.

The result of the Initializer is a Template Engine which should always be assigned to esx. This is important for editor syntax support. The Template Engine instance is a template tag function.

import createEsx from 'esx'
import App from 'components/App'
const esx = createEsx({ App }) // same as {App: App}
// `esx` is the Template Engine
console.log(esx `<App/>`) // exactly same result as React.createElement(App)

A component must be one of the following

• function
• class
• symbol
• object with a $$typeof key
• string representing an element (e.g. 'div')

Components passed to the Initializer are registered and validated at initialization time. Each key in the components object should correspond to the name of a component referenced within an ESX template literal.

Components can also be registered after initialization with the esx.register method:

import createEsx from 'esx'
import App from 'components/App'
const esx = createEsx()
esx.register({ App })
// exactly same result as React.createElement(App)
console.log(esx `<App/>`) 

Each key in the components object should correspond to the name of a component as referenced within an ESX template literal.

A single component can be registered with the esx.register.one method. The supplied name parameter must correspond to the name of a component referenced within an ESX template literal and the component parameter will be validated.

Advanced use only. Use with care. This is a performance escape hatch. This method will register components without validating. This may be used for performance reasons such as when needing to register a component within a function. It is recommended to use the non-lax methods unless component validation in a specific scenario is measured as a bottleneck.

Advanced use only. Use with care. This is a performance escape hatch. Will register one component without validating.

On the server side every Template Engine instance also has a renderToString method. The esx.renderToString method is also a template literal tag function.

This must be used in place of the react-dom/server packages renderToString method in order to obtain the speed benefits.

import createEsx from 'esx'
import App from 'components/App'
const esx = createEsx()
esx.register({ App })
// same, but faster, result as ReactDomServer.renderToString(<App/>)
console.log(esx.renderToString `<App/>`)

Alias: esx.ssr

The esx.renderToString method can also accept an element as its only parameter.

import createEsx from 'esx'
import App from 'components/App'
const esx = createEsx()
esx.register({ App })
const app = esx `<App/>`
// same, but faster, result as ReactDomServer.renderToString(app)
console.log(esx.renderToString(app))

Elements created with esx contain template information and can be used for high performance rendering, whereas a plain React element at the root could only ever be rendered with ReactDomServer.renderToString.

That is why esx.renderToString will throw if passed a plain React element:

// * DON'T DO THIS!: *
esx.renderToString(React.createElement('div')) // => throws Error
// instead do this:
esx.renderToString `<div/>`
// or this: 
esx.renderToString(esx `<div/>`)

On the server side the Initializer has an ssr property, which has an options method. The follow options are supported:

By default the hooks-mode option is compatible with React server side rendering. This means that any stateful hooks, e.g. useState and useReducer do not actually retain state between renders.

The following will set hooks-mode to stateful:

createEsx.ssr.option('hooks-mode', 'stateful')

This means that useState, useReducer, useMemo and useCallback have the same stateful behaviour as their client-side counterpart hooks. The state is retained between renderToString calls, instead of always returning the initial state as with compatible mode. This can be useful where a server-side render-to-hydrate strategy is employed and a great fit with rendering on server initialize.

esx is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

https://github.com/davidmarkclements

https://www.npmjs.com/~davidmarkclements

https://twitter.com/davidmarkclem

esx was preceded by... esx. The esx namespace was registered four years ago by a prior author Mattéo Delabre , with a similar idea. He kindly donated the namespace to this particular manifestation of the idea. For this reason, esx versioning begins at v2.x.x. Versions 0.x.x and 1.x.x are deprecated.

esx is directly inspired by hyperx, which was the first known library to this authors knowledge to make the point that template strings are perfect for generating both virtual doms and server side rendering. What hyperx lacks, however, is a way to represent React components within its template syntax. It is only for generating HTML nodes.

It's not uncommon for similar ideas to be had and implemented concurrently without either party knowing of the other. While htm was first released early 2019, work on esx had already been on-going some months prior. However the mission of esx is slightly broader, with a primary objective being to speed up server side rendering, so it took longer to release.

MIT

• nearForm