If you need help with Server Side Rendering and performance, contact me.
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/optimize my-app.js
Note: transpiling is still experimental.
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})
- Components must be registered with
react
v16.8+ is required as a peer dependencyreact-dom
v16.8+ is required as a peer dependencyesx
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/>`)
Pre and Post plugins are also provided to allow for additional manipulation of templates and output. A Post plugin could be used to write output directly to a stream, or inject additional HTML.
The esx.plugins.pre
method registers a Pre plugin. Plugins
will be executed in the order that there are registered.
A Pre plugin should be passed a function that has the same signature as a tagged template function.
It must return an array containing two arrays. The first is an array of strings, the second is an array of values.
The pre plugin can be used to reshape the strings array and/or apply mutations to the interpolated values. An example of a Pre plugin could be to apply a transform, turning an alternative template syntax (such as Pug) into ESX syntax.
The esx.plugins.post
method registers a Post plugin. Plugins
will be executed in the order that there are registered. Unlike
Pre plugins, Post plugins can only be used Server Side and will
only be invoked for components that are rendered via esx.renderToString
.
A Post plugin is passed the HTML string output of a component at the time it is rendered. A Post plugin can be used to inject extra HTML, apply additional transforms to the HTML, or capture the HTML as each component is being rendered.
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.