Asynchronous React VirtualDOM renderer for SSR.
npm install rapscallion 
Rapscallion is a React VirtualDOM renderer for the server. Its notable features are as follows:
- Rendering is asynchronous and non-blocking.
- Rapscallion is roughly 30% faster than renderToString.
- It provides a streaming interface so that you can start sending content to the client immediately.
- It provides a templating feature, so that you can wrap your component's HTML in boilerplate without giving up benefits of streaming.
- It provides a component caching API to further speed-up your rendering.
- Installation
- API
- render
- Renderer#toPromise
- Renderer#toStream
- Renderer#includeDataReactAttrs
- Renderer#tuneAsynchronicity
- Renderer#checksum
- setCacheStrategy
- template
- Valid expressions
- Behavior
- Example
- Caching
- Babel Plugins
- babel-plugin-client
- babel-plugin-server
- Benchmarks
- License
Using npm:
``shell`
$ npm install --save rapscallion
In Node.js:
`javascript
const {
render,
template
} = require("rapscallion");
// ...
`
render(VirtualDomNode) -> Renderer
This function returns a Renderer, an interface for rendering your VirtualDOM element. Methods are enumerated below.
-----
renderer.toPromise() -> Promise
This function evaluates the React VirtualDOM Element originally provided to the renderer, and returns a Promise that resolves to the component's evaluated HTML string.
Example:
`javascript`
render(
.toPromise()
.then(htmlString => console.log(htmlString));
-----
renderer.toStream() -> NodeStream
This function evaluates a React VirtualDOM Element, and returns a Node stream. This stream will emit string segments of HTML as the DOM tree is asynchronously traversed and evaluated.
In addition to the normal API for Node streams, the returned stream object has a checksum method. When invoked, this will return the checksum that has been calculated up to this point for the stream. If the stream has ended, the checksum will be the same as would be included by React.renderToString.
Example:
`javascript`
app.get('/example', function(req, res){
render(
.toStream()
.pipe(res);
});
-----
renderer.includeDataReactAttrs(Boolean) -> undefined
This allows you to set whether you'd like to include properties like data-reactid in your rendered markup.
-----
renderer.tuneAsynchronicity(PositiveInteger) -> undefined
Rapscallion allows you to tune the asynchronicity of your renders. By default, rapscallion batches events in your stream of HTML segments. These batches are processed in a synchronous-like way. This gives you the benefits of asynchronous rendering without losing too much synchronous rendering performance.
The default value is 100, which means the Rapscallion will process one hundred segments of HTML text before giving control back to the event loop.
You may want to change this number if your server is under heavy load. Possible values are the set of all positive integers. Lower numbers will be "more asynchronous" (shorter periods between I/O processing) and higher numbers will be "more synchronous" (higher performance).
-----
renderer.checksum() -> Integer
In a synchronous rendering environment, the generated markup's checksum would be calculated after all generation has completed. It would then be attached to the start of the HTML string before being sent to the client.
However, in the case of a stream, the checksum is only known once all markup is generated, and the first bits of HTML are already on their way to the client by then.
The renderer's checksum method will give you access to the checksum that has been calculated up to this point. If the rendered has completed generating all markup for the provided component, this value will be identical to that provided by React's renderToString function.
For an example of how to attach this value to the DOM on the client side, see the example in the template section below.
-----
setCacheStrategy({ get: ..., set: ... */ }) -> undefined
The default cache strategy provided by Rapscallion is a naive one. It is synchronous and in-memory, with no cache invalidation or TTL for cache entries.
However, setCacheStrategy is provided to allow you to integrate your own caching solutions. The function expects an options argument with two keys:
- get should accept a single argument, the key, and return a Promise resolving to a cached value. If no cached value is found, the Promise should resolve to null.set
- should accept two arguments, a key and its value, and return a Promise that resolves when the set operation has completed.
All values, both those returned from get and passed to set, will be Arrays with both string and integer elements. Keep that in mind if you need to serialize the data for your cache backend.
Example:
`javascript
const { setCacheStrategy } = require("rapscallion");
const redis = require("redis");
const client = redis.createClient();
const redisGet = Promise.promisify(redisClient.get, { context: redisClient });
const redisSet = Promise.promisify(redisClient.set, { context: redisClient });
setCacheStrategy({
get: key => redisGet(key).then(val => val && JSON.parse(val) || null),
set: (key, val) => redisSet(key, JSON.stringify(val))
});
`
For more information on how to cache your component HTML, read through the caching section below.
-----
templateTEMPLATE LITERAL -> Renderer
With React's default renderToString, it is a common pattern to define a function that takes the rendered output and inserts it into some HTML boilerplate; tags and the like.
Rapscallion allows you to stream the rendered content of your components as they are generated. However, this makes it somewhat less simple to wrap that component in your HTML boilerplate.
Fortunately, Rapscallion provides _rendering templates_. They look very similar to normal template strings, except that you'll prepend it with template as a template-literal tag.
#### Valid expressions
Like string templates, rendering templates allow you to insert expressions of various types. The following expression types are allowed:
- string: any expression that evaluates to a string, i.e. template${ "my string" }
- vdom: any React VirtualDOM object, i.e. template${
- Renderer: any instance, i.e. template ${ render(
- function: any function that, when invoked, evaluates to one of the other valid expression types, i.e. template${ () => "my string" } One important thing to note is that a rendering template returns a
instance when evaluated. This means that templates can be composed like so:`javascript
const myComponent = template;const html = template
;
`#### Behavior
To utilize rendering templates effectively, it will be important to understand their following three properties:
1. template segments are evaluated _asynchronously_;
2. template segments are evaluated _in order_; and
3. template segments are evaluated _lazily_, as they are consumed.
These properties are actually true of all
s. However, they present potential pitfalls in the more complex situations that templates often represent. The asynchronicity is the easiest of the three properties to understand, so not much time will be spent on that. It is the lazy orderedness that can introduce interesting ramifications.Here are a handful of consequences of these properties that might not be readily apparent:
- You cannot instantiate a component, pass it a store, and immediately pull out an updated state from the store. You have to wait until after the component is fully rendered before any side-effects of that rendering occur.
- The same is true of checksums. You can't get a checksum of a component that hasn't been rendered yet.
- If an error occurs half-way through a render, and you are streaming content to the user, it is too late to send a
404 - because you've already sent a 200. You'll have to find other ways to present error conditions to the client.However, these properties also allow the computation cost to be spread across the lifetime of the render, and ultimately make things like asynchronous rendering possible.
#### Example
All of this may be somewhat unclear in the abstract, so here's a fuller example:
`javascript
import { render, template } from "rapscallion";// ...
app.get('/example', function(req, res){
// ...
const store = createStore(/ ... /);
const componentRenderer = render(
const responseRenderer = template
; responseRenderer.toStream().pipe(res);
});
`Note that the template comprises a stream of HTML text (
), the HTML from a second component (MyOtherComponent), and a function that evaluates to the store's state - something you'll often want to do with SSR.Additionally, we attach the checksum to the rendered component's DOM element on the client side.
-----
Caching
Caching is performed on a per-component level, is completely opt-in, and should be used judiciously. The gist is this: you define a
cacheKey prop on your component, and that component will only be rendered once for that particular key. cacheKey can be set on both React components and html React elements.If you cache components that change often, this will result in slower performance. But if you're careful to cache only those components for which 1) a
cacheKey is easy to compute, and 2) will have a small set of keys (i.e. the props don't change often), you can see considerable performance improvements.Example:
`javascript
const Child = ({ val }) => (
ComponentA
);const Parent = ({ toVal }) => (
Parent:${toVal} }>
{
_.range(toVal).map(val => (
Child:${val} } key={val} />
))
}
);Promise.resolve()
// The first render will take the expected duration.
.then(() => render(
// The second render will be much faster, due to multiple cache hits.
.then(() => render(
// The third render will be near-instantaneous, due to a top-level cache hit.
.then(() => render(
`
-----
Babel Plugins
Rapscallion ships with two Babel plugins, one intended for your server build and one for your client build. Each serves a different purpose.
$3
When running in development mode,
checks the DOM elements you define for any invalid HTML attributes. When found, a warning is issued in the console.If you're utilizing Rapscallion's caching mechanisms, you will see warnings for the
cacheKey props that you define on your elements. Additionally, these properties are completely useless on the client, since they're only utilized during SSR.Rapscallion's client plugin will strip
cacheKey props from your build, avoiding the errors and removing unnecessary bits from your client build.To use, add the following to your
.babelrc:`json
{
"plugins": [
"rapscallion/babel-plugin-client",
// ...
]
}
`$3
In typical scenarios, developers will use the
plugin to transform their JSX into React.createElement calls. However, these createElement function calls involve run-time overhead that is ultimately unnecessary for SSR.Rapscallion's server plugin is provided as a more efficient alternative. It provides two primary benefits:
Efficient VDOM data-structure: Instead of transforming JSX into
React.createElement calls, Rapscallion's server plugin transforms JSX into a simple object/array data-structure. This data-structure is more efficient to traverse and avoids extraneous function invocations.Pre-rendering: Rapscallion's server plugin also attempts to pre-render as much content as possible. For example, if your component always starts with a
, that fact can be determined at build-time. Transforming JSX into these pre-computed string segments avoids computation cost at run-time, and in some cases can make for a more shallow VDOM tree.To be clear,
rapscallion/babel-plugin-server should be used _in place of_ babel-plugin-transform-react-jsx.To use, add the following to your
.babelrc:`json
{
"plugins": [
"rapscallion/babel-plugin-server",
// ...
]
}
`The plugin also supports Rapscallion-aware JSX hoisting. This may improve performance, but may also hurt. We recommend you profile your application's rendering behavior to determine whether to enable hoisting. To use:
json
{
"plugins": [
["rapscallion/babel-plugin-server", {
"hoist": true
}]
]
}
`
-----
Benchmarks
The below benchmarks _do not_ represent a typical use-case. Instead, they represent the absolute _best case scenario_ for component caching.
However, you'll note that even without caching, a concurrent workload will be processed almost 50% faster, without any of the blocking!
Starting benchmark for 10 concurrent render operations...
renderToString took 9.639041541 seconds
rapscallion, no caching took 9.168861890 seconds; ~1.05x faster
rapscallion, caching DIVs took 3.830723252 seconds; ~2.51x faster
rapscallion, caching DIVs (second time) took 3.004709954 seconds; ~3.2x faster
rapscallion, caching Components took 3.088687965 seconds; ~3.12x faster
rapscallion, caching Components (second time) took 2.484650701 seconds; ~3.87x faster
rapscallion (pre-rendered), no caching took 7.423578183 seconds; ~1.29x faster
rapscallion (pre-rendered), caching DIVs took 3.202458180 seconds; ~3x faster
rapscallion (pre-rendered), caching DIVs (second time) took 2.671346947 seconds; ~3.6x faster
rapscallion (pre-rendered), caching Components took 2.578935599 seconds; ~3.73x faster
rapscallion (pre-rendered), caching Components (second time) took 2.470472298 seconds; ~3.9x faster
-----