{"id":13394332,"url":"https://github.com/FormidableLabs/rapscallion","last_synced_at":"2025-03-13T20:31:27.577Z","repository":{"id":65372033,"uuid":"80715274","full_name":"FormidableLabs/rapscallion","owner":"FormidableLabs","description":"Asynchronous React VirtualDOM renderer for SSR.","archived":true,"fork":false,"pushed_at":"2022-02-18T22:39:41.000Z","size":286,"stargazers_count":1396,"open_issues_count":22,"forks_count":68,"subscribers_count":73,"default_branch":"master","last_synced_at":"2024-05-14T04:01:09.509Z","etag":null,"topics":["asynchronous","html","react","react-dom","render","server-side-rendering","stream"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FormidableLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-02T10:36:12.000Z","updated_at":"2024-05-14T04:01:09.510Z","dependencies_parsed_at":"2023-01-19T23:16:43.841Z","dependency_job_id":null,"html_url":"https://github.com/FormidableLabs/rapscallion","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Frapscallion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Frapscallion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Frapscallion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormidableLabs%2Frapscallion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FormidableLabs","download_url":"https://codeload.github.com/FormidableLabs/rapscallion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243159455,"owners_count":20245726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asynchronous","html","react","react-dom","render","server-side-rendering","stream"],"created_at":"2024-07-30T17:01:16.266Z","updated_at":"2025-03-13T20:31:27.109Z","avatar_url":"https://github.com/FormidableLabs.png","language":"JavaScript","readme":"# Rapscallion\n\n[![CircleCI](https://circleci.com/gh/FormidableLabs/rapscallion.svg?style=svg)](https://circleci.com/gh/FormidableLabs/rapscallion) [![Join the chat at https://gitter.im/FormidableLabs/rapscallion](https://badges.gitter.im/FormidableLabs/rapscallion.svg)](https://gitter.im/FormidableLabs/rapscallion?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n## Overview\n\nRapscallion is a React VirtualDOM renderer for the server.  Its notable features are as follows:\n\n- Rendering is **asynchronous and non-blocking**.\n- Rapscallion is roughly **30% faster** than `renderToString`.\n- It provides a streaming interface so that you can **start sending content to the client immediately**.\n- It provides a templating feature, so that you can **wrap your component's HTML in boilerplate** without giving up benefits of streaming.\n- It provides a **component caching** API to further speed-up your rendering.\n\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Installation](#installation)\n- [API](#api)\n  - [`render`](#render)\n  - [`Renderer#toPromise`](#renderertopromise)\n  - [`Renderer#toStream`](#renderertostream)\n  - [`Renderer#includeDataReactAttrs`](#rendererincludedatareactattrs)\n  - [`Renderer#tuneAsynchronicity`](#renderertuneasynchronicity)\n  - [`Renderer#checksum`](#rendererchecksum)\n  - [`setCacheStrategy`](#setcachestrategy)\n  - [`template`](#template)\n    - [Valid expressions](#valid-expressions)\n    - [Behavior](#behavior)\n    - [Example](#example)\n- [Caching](#caching)\n- [Babel Plugins](#babel-plugins)\n  - [`babel-plugin-client`](#babel-plugin-client)\n  - [`babel-plugin-server`](#babel-plugin-server)\n- [Benchmarks](#benchmarks)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\nUsing npm:\n```shell\n$ npm install --save rapscallion\n```\n\nIn Node.js:\n```javascript\nconst {\n  render,\n  template\n} = require(\"rapscallion\");\n\n// ...\n```\n\n\n## API\n\n\n### `render`\n\n`render(VirtualDomNode) -\u003e Renderer`\n\nThis function returns a Renderer, an interface for rendering your VirtualDOM element.  Methods are enumerated below.\n\n-----\n\n### `Renderer#toPromise`\n\n`renderer.toPromise() -\u003e Promise\u003cString\u003e`\n\nThis function evaluates the React VirtualDOM Element originally provided to the renderer, and returns a Promise that resolves to the component's evaluated HTML string.\n\n**Example:**\n\n```javascript\nrender(\u003cMyComponent {...props} /\u003e)\n  .toPromise()\n  .then(htmlString =\u003e console.log(htmlString));\n```\n\n\n-----\n\n### `Renderer#toStream`\n\n`renderer.toStream() -\u003e NodeStream\u003cStringSegment\u003e`\n\nThis 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.\n\nIn 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`.\n\n**Example:**\n\n```javascript\napp.get('/example', function(req, res){\n  render(\u003cMyComponent prop=\"stuff\" /\u003e)\n    .toStream()\n    .pipe(res);\n});\n```\n\n\n-----\n\n### `Renderer#includeDataReactAttrs`\n\n`renderer.includeDataReactAttrs(Boolean) -\u003e undefined`\n\nThis allows you to set whether you'd like to include properties like `data-reactid` in your rendered markup.\n\n\n-----\n\n### `Renderer#tuneAsynchronicity`\n\n`renderer.tuneAsynchronicity(PositiveInteger) -\u003e undefined`\n\nRapscallion 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.\n\nThe default value is `100`, which means the Rapscallion will process one hundred segments of HTML text before giving control back to the event loop.\n\nYou 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).\n\n\n-----\n\n### `Renderer#checksum`\n\n`renderer.checksum() -\u003e Integer`\n\nIn 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.\n\nHowever, 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.\n\nThe 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.\n\nFor an example of how to attach this value to the DOM on the client side, see the example in the [template](#template) section below.\n\n\n-----\n\n### `setCacheStrategy`\n\n`setCacheStrategy({ get: ..., set: ... */ }) -\u003e undefined`\n\nThe 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.\n\nHowever, `setCacheStrategy` is provided to allow you to integrate your own caching solutions.  The function expects an options argument with two keys:\n\n- `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`.\n- `set` should accept two arguments, a key and its value, and return a Promise that resolves when the `set` operation has completed.\n\nAll 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.\n\n**Example:**\n\n```javascript\nconst { setCacheStrategy } = require(\"rapscallion\");\nconst redis = require(\"redis\");\n\nconst client = redis.createClient();\nconst redisGet = Promise.promisify(redisClient.get, { context: redisClient });\nconst redisSet = Promise.promisify(redisClient.set, { context: redisClient });\nsetCacheStrategy({\n  get: key =\u003e redisGet(key).then(val =\u003e val \u0026\u0026 JSON.parse(val) || null),\n  set: (key, val) =\u003e redisSet(key, JSON.stringify(val))\n});\n```\n\nFor more information on how to cache your component HTML, read through the [caching section](#caching) below.\n\n\n-----\n\n### `template`\n\n``template`TEMPLATE LITERAL` -\u003e Renderer``\n\nWith 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; `\u003chtml\u003e` tags and the like.\n\nRapscallion 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.\n\nFortunately, 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals).\n\n#### Valid expressions\n\nLike string templates, rendering templates allow you to insert expressions of various types.  The following expression types are allowed:\n\n- **string:** any expression that evaluates to a string, i.e. `` template`\u003chtml\u003e${ \"my string\" }\u003c/html\u003e` ``\n- **vdom:** any React VirtualDOM object, i.e. `` template`\u003chtml\u003e${ \u003cMyComponent /\u003e }\u003c/html\u003e``\n- **Renderer:** any `Renderer` instance, i.e. `` template `\u003chtml\u003e${ render(\u003cdiv /\u003e) }\u003c/html\u003e` ``\n- **function:** any function that, when invoked, evaluates to one of the other valid expression types, i.e. `` template`\u003chtml\u003e${ () =\u003e \"my string\" }\u003c/html\u003e` ``\n\nOne important thing to note is that a rendering template returns a `Renderer` instance when evaluated.  This means that templates can be composed like so:\n\n```javascript\nconst myComponent = template`\n\u003cdiv\u003e\n  ${ \u003cMyComponent /\u003e }\n\u003c/div\u003e\n`;\n\nconst html = template`\n\u003chtml\u003e\n${ \u003cMyHeader /\u003e }\n\u003cbody\u003e\n  ${ myComponent }\n\u003c/body\u003e\n\u003c/html\u003e\n`;\n```\n\n#### Behavior\n\nTo utilize rendering templates effectively, it will be important to understand their following three properties:\n\n1. template segments are evaluated _asynchronously_;\n2. template segments are evaluated _in order_; and\n3. template segments are evaluated _lazily_, as they are consumed.\n\nThese properties are actually true of all `Renderer`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.\n\nHere are a handful of consequences of these properties that might not be readily apparent:\n\n- 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.\n- The same is true of checksums.  You can't get a checksum of a component that hasn't been rendered yet.\n- 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.\n\nHowever, these properties also allow the computation cost to be spread across the lifetime of the render, and ultimately make things like asynchronous rendering possible.\n\n\n#### Example\n\nAll of this may be somewhat unclear in the abstract, so here's a fuller example:\n\n```javascript\nimport { render, template } from \"rapscallion\";\n\n// ...\n\napp.get('/example', function(req, res){\n  // ...\n\n  const store = createStore(/* ... */);\n  const componentRenderer = render(\u003cMyComponent store={store} /\u003e);\n\n  const responseRenderer = template`\n    \u003chtml\u003e\n    \u003cbody\u003e\n      ${componentRenderer}\n      ${\n        \u003cMyOtherComponent /\u003e\n      }\n      \u003cscript\u003e\n        // Expose initial state to client store bootstrap code.\n        window._initialState = ${() =\u003e JSON.stringify(store.getState()).replace(/\u003c/g, '\\\\u003c')};\n        // Attach checksum to the component's root element.\n        document.querySelector(\"#id-for-component-root\").setAttribute(\"data-react-checksum\", \"${() =\u003e componentRenderer.checksum()}\")\n        // Bootstrap your application here...\n      \u003c/script\u003e\n    \u003c/body\u003e\n    \u003c/html\u003e\n  `;\n\n  responseRenderer.toStream().pipe(res);\n});\n```\n\nNote that the template comprises a stream of HTML text (`componentRenderer`), 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.\n\nAdditionally, we attach the checksum to the rendered component's DOM element on the client side.\n\n\n-----\n\n## Caching\n\nCaching 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.\n\nIf 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.\n\n**Example:**\n\n```javascript\nconst Child = ({ val }) =\u003e (\n  \u003cdiv\u003e\n    ComponentA\n  \u003c/div\u003e\n);\n\nconst Parent = ({ toVal }) =\u003e (\n  \u003cdiv cacheKey={ `Parent:${toVal}` }\u003e\n    {\n      _.range(toVal).map(val =\u003e (\n        \u003cChild cacheKey={ `Child:${val}` } key={val} /\u003e\n      ))\n    }\n  \u003c/div\u003e\n);\n\nPromise.resolve()\n  // The first render will take the expected duration.\n  .then(() =\u003e render(\u003cParent toVal={5} /\u003e).toPromise())\n  // The second render will be much faster, due to multiple cache hits.\n  .then(() =\u003e render(\u003cParent toVal={6} /\u003e).toPromise())\n  // The third render will be near-instantaneous, due to a top-level cache hit.\n  .then(() =\u003e render(\u003cParent toVal={6} /\u003e).toPromise());\n```\n\n\n-----\n\n## Babel Plugins\n\nRapscallion ships with two Babel plugins, one intended for your server build and one for your client build.  Each serves a different purpose.\n\n### `babel-plugin-client`\n\nWhen running in development mode, `ReactDOM.render` checks the DOM elements you define for any invalid HTML attributes.  When found, a warning is issued in the console.\n\nIf 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.\n\nRapscallion's client plugin will strip `cacheKey` props from your build, avoiding the errors and removing unnecessary bits from your client build.\n\nTo use, add the following to your `.babelrc`:\n\n```json\n{\n  \"plugins\": [\n    \"rapscallion/babel-plugin-client\",\n    // ...\n  ]\n}\n```\n\n### `babel-plugin-server`\n\nIn typical scenarios, developers will use the `babel-plugin-transform-react-jsx` plugin to transform their JSX into `React.createElement` calls.  However, these `createElement` function calls involve run-time overhead that is ultimately unnecessary for SSR.\n\nRapscallion's server plugin is provided as a more efficient alternative.  It provides two primary benefits:\n\n**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.\n\n**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 `\u003cdiv\u003e`, 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.\n\nTo be clear, `rapscallion/babel-plugin-server` should be used _in place of_ `babel-plugin-transform-react-jsx`.\n\nTo use, add the following to your `.babelrc`:\n\n```json\n{\n  \"plugins\": [\n    \"rapscallion/babel-plugin-server\",\n    // ...\n  ]\n}\n```\n\nThe 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:\n\n```json\n{\n  \"plugins\": [\n    [\"rapscallion/babel-plugin-server\", {\n      \"hoist\": true\n    }]\n  ]\n}\n```\n\n\n-----\n\n## Benchmarks\n\nThe below benchmarks _do not_ represent a typical use-case.  Instead, they represent the absolute _best case scenario_ for component caching.\n\nHowever, you'll note that even without caching, a concurrent workload will be processed almost 50% faster, without any of the blocking!\n\n```\nStarting benchmark for 10 concurrent render operations...\nrenderToString took 9.639041541 seconds\nrapscallion, no caching took 9.168861890 seconds; ~1.05x faster\nrapscallion, caching DIVs took 3.830723252 seconds; ~2.51x faster\nrapscallion, caching DIVs (second time) took 3.004709954 seconds; ~3.2x faster\nrapscallion, caching Components took 3.088687965 seconds; ~3.12x faster\nrapscallion, caching Components (second time) took 2.484650701 seconds; ~3.87x faster\nrapscallion (pre-rendered), no caching took 7.423578183 seconds; ~1.29x faster\nrapscallion (pre-rendered), caching DIVs took 3.202458180 seconds; ~3x faster\nrapscallion (pre-rendered), caching DIVs (second time) took 2.671346947 seconds; ~3.6x faster\nrapscallion (pre-rendered), caching Components took 2.578935599 seconds; ~3.73x faster\nrapscallion (pre-rendered), caching Components (second time) took 2.470472298 seconds; ~3.9x faster\n```\n\n\n-----\n\n## License\n\n[MIT License](http://opensource.org/licenses/MIT)\n\n\n## Maintenance Status\n\n**Archived:** This project is no longer maintained by Formidable. We are no longer responding to issues or pull requests unless they relate to security concerns. We encourage interested developers to fork this project and make it their own!\n","funding_links":[],"categories":["目录","JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFormidableLabs%2Frapscallion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFormidableLabs%2Frapscallion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFormidableLabs%2Frapscallion/lists"}