react_on_rails_pro 16.2.0.beta.8

data/docs/home-pro.md

@@ -0,0 +1,146 @@
+# React on Rails Pro
+
+Node rendering and caching performance enhancements for [React on Rails](https://github.com/shakacode/react_on_rails). Now supports React 18 with updates to React on Rails! Check the [React on Rails CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for details and the updates to the [loadable-components instructions](https://github.com/shakacode/react_on_rails_pro/blob/master/docs/code-splitting-loadable-components.md).
+
+## Getting Started
+The best way to see how React on Rails Pro works is to install this repo locally and take a look at
+the example application:
+
+[spec/dummy](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/README.md)
+1. Uses a @rails/webpacker standard configuration.
+1. Has pages that demonstrate:
+   1. caching
+   2. loadable-components
+1. Has all the basic react_on_rails specs that run against the Node Renderer 
+1. Demonstrates using HMR and loadable-components with almost the same example that is present in [loadable-components for SSR](https://github.com/gregberge/loadable-components/tree/main/examples/server-side-rendering)
+   
+See the README.md in those sample apps for more details.
+
+## Features
+
+### 🚀 Next-Gen Server Rendering: Streaming with React 18's Latest APIs
+React on Rails Pro supports React 18's Streaming Server-Side Rendering, allowing you to progressively render and stream HTML content to the client. This enables faster page loads and better user experience.
+
+See [docs/streaming-server-rendering](./streaming-server-rendering.md) for more details.
+
+### Caching
+Caching of SSR is critical for achieving optimum performance.
+
+* **Fragment Caching**: for `react_component` and `react_component_hash`, including lazy evaluation of props.
+* **Prerender Caching**: Server rendering JavaScript evaluation is cached if `prerender_caching` is turned on in your Rails config. This applies to all JavaScript evaluation methods.
+
+See [docs/caching](./caching.md) for more details.
+
+### Clearing of Global State
+Suppose you detect that some library used in server-rendering is leaking state between calls to server render. In that case, you can set the `config.ssr_pre_hook_js` in your `config/initializers/react_on_rails_pro.rb` to run some JavaScript to clear the globally leaked state at the beginning of each call to server render.
+
+For more details, see [Rails Configuration](https://github.com/shakacode/react_on_rails/blob/master/docs/configuration.md).
+
+### React On Rails Pro Node Renderer
+The "React on Rails Pro Node Renderer" provides more efficient server rendering on a standalone Node JS server.
+See the [Node Renderer Docs](./node-renderer/basics.md).
+
+### Bundle Caching
+Don't wait for the same webpack bundles to be built over and over. See the [bundle-caching docs](./bundle-caching.md).
+
+## Other Utility Methods
+See the [Ruby API](./ruby-api.md).
+
+## References
+
+* [Installation](./installation.md)
+* [Streaming Server Rendering](./streaming-server-rendering.md)
+* [Caching](./caching.md)
+* [Rails Configuration](./configuration.md)
+* [Node Renderer Docs](./node-renderer/basics.md)
+
+# Features
+## Code Splitting
+
+From [The Cost of JavaScript in 2018](https://medium.com/@addyosmani/the-cost-of-javascript-in-2018-7d8950fbb5d4):
+
+> To stay fast, only load JavaScript needed for the current page. Prioritize what a user will need and lazy-load the rest with code-splitting. This gives you the best chance at loading and getting interactive fast. Stacks with route-based code-splitting by default are game-changers.
+
+
+## Caching
+### Server Rendering
+Server rendering of JavaScript evaluation is cached if `prerender_caching` is turned on in your Rails config. This applies to all JavaScript evaluation methods, including ExecJS and the Node VM Renderer.
+
+### Pro: Fragment Caching
+
+Fragment caching is a [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) feature. Fragment caching is a **HUGE** performance booster for your apps. Use the `cached_react_component` and `cached_react_component_hash`. The API is the same as `react_component` and `react_component_hash`, but for 2 differences:
+
+1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
+1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
+
+```ruby
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
+  some_slow_method_that_returns_props
+end %>
+```
+
+Such fragment caching saves CPU work for your web server and greatly reduces the request time. It completely skips the evaluation costs of:
+
+1. Database calls to compute the props.
+2. Serialization the props values hash into a JSON string for evaluating JavaScript to server render.
+3. Costs associated with evaluating JavaScript from your Ruby code.
+4. Creating the HTML string containing the props and the server-rendered JavaScript code.
+
+Note, even without server rendering (without step 3 above), fragment caching is still effective.
+See [Caching](./caching.md) for more additional details.
+
+## React On Rails Pro Node React Render
+The "React on Rails Pro Node React Renderer" provides more efficient React Server Side Rendering on a standalone Node JS server.
+
+### Overall Management Memory and CPU on both the Rendering and Ruby Servers
+A separate Node rendering server is easier to manage in terms of monitoring memory and CPU performance, allocating dynos, etc. This also makes it easier to manage the ruby servers, as you no longer have to consider the impact of starting an embedded V8. Thus, you can never hang your Ruby servers due to JavaScript memory leaks.
+
+### Proper Node Tooling
+A disadvantage of Ruby embedded JavaScript (ExecJS) is that it precludes the use of standard Node tooling for doing things like profiling and tracking down memory leaks. With the renderer on a separate Node.js server, we were able to use node-memwatch (https://github.com/marcominetti/node-memwatch) to find few memory leaks in the Egghead React code.
+
+### Caching of React Rendering
+To limit the load on the renderer server or embedded ExecJS, caching of React rendering requests can be enabled by a config setting. Because current React rendering requests are idempotent (same value regardless of calls), caching should be feasible for all server rendering calls. The current renderer does not allow any asynchronous calls to fetch data. The rendering request includes all data for rendering.
+
+### Rolling Restart of Node Workers
+Due to poor performance and crashes due to memory leaks, the rolling restart of node workers was thus added as an option to the core rendering product. This option is cheap insurance against the renderer getting too slow from a memory leak due to a bug in some newly deployed JavaScript code.
+
+### Docs
+See the [Node React Render Docs](./node-renderer/basics.md).
+
+## Other Utility Methods
+See the [Ruby API](./ruby-api.md).
+
+# Testimonials
+
+"Do you want your app to randomly crash sometimes in hard to predict ways? Then ExecJS is perfect for you"
+Anybody who regularly hits six-digit request numbers a day is going to be in for a bad time." Pete Keen, https://egghead.io
+
+For details, see [Egghead React on Rails Pro Deployment Highlights](https://github.com/shakacode/react_on_rails/wiki/Egghead-React-on-Rails-Pro-Deployment-Highlights/).
+
+# FAQ
+
+## Why should I use React on Rails Pro if ExecJS seems to work?
+
+Caching is extremely useful to any server rendering you're doing, with or without ExecJS. 
+
+React on Rails pro support caching at 2 levels:
+1. Caching of rendering request to ExecJS (or the Node renderer). This avoids extra calls to ExecJS.
+2. Fragment caching of server rendering. This avoids even the calculations of prop values from the database and the cost of converting the props to a string (lots of CPU there)
+
+By doing such caching, you will take a CPU load off your Ruby server as well as improving response time. And this is with virtually no code changes on your part.
+
+# Support React on Rails development
+
+Support React on Rails development [by becoming a Github sponsor](https://github.com/sponsors/shakacode) and get these benefits:
+
+1. 1-hour per month of support via Slack, PR reviews, and Zoom for React on Rails,
+   React-Rails, Shakapacker, rails/webpacker, ReScript (ReasonML), TypeScript, Rust, etc.
+2. React on Rails Pro Software that extends React on Rails with Node server rendering,
+   fragment caching, code-splitting, and other performance enhancements for React on Rails.
+
+For more info, email [justin@shakacode.com](mailto:justin@shakacode.com).
+
+# References
+
+* [Caching](./caching.md)
+* [Rails Configuration](./configuration.md)

data/docs/installation.md

@@ -0,0 +1,203 @@
+# Installation
+
+React on Rails Pro packages are published publicly on npmjs.org and RubyGems.org. Installation requires a valid **license token** for runtime validation. Contact [justin@shakacode.com](mailto:justin@shakacode.com) to purchase a license.
+
+**Upgrading from GitHub Packages?** See the [Upgrading Guide](./updating.md) for migration instructions.
+
+Check the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) to see what version you want.
+
+## Version Format
+
+For the below docs, find the desired `<version>` in the CHANGELOG. Note that for pre-release versions:
+
+- Gems use all periods: `16.2.0.beta.1`
+- NPM packages use dashes: `16.2.0-beta.1`
+
+# Ruby Gem Installation
+
+## Prerequisites
+
+Ensure your **Rails** app is using the **react_on_rails** gem, version 16.0.0 or higher.
+
+## Install react_on_rails_pro Gem
+
+Add the `react_on_rails_pro` gem to your **Gemfile**:
+
+```ruby
+gem "react_on_rails_pro", "~> 16.2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install react_on_rails_pro --version "<version>"
+```
+
+## License Configuration
+
+Set your license token as an environment variable:
+
+```bash
+export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
+```
+
+Or configure it in your Rails initializer (not recommended for production):
+
+```ruby
+# config/initializers/react_on_rails_pro.rb
+ReactOnRailsPro.configure do |config|
+  config.license_token = ENV["REACT_ON_RAILS_PRO_LICENSE"]
+end
+```
+
+⚠️ **Security Warning**: Never commit your license token to version control. Always use environment variables or secure secret management systems (like Rails credentials, Heroku config vars, AWS Secrets Manager, etc.).
+
+## Rails Configuration
+
+You don't need to create an initializer if you are satisfied with the defaults as described in [Configuration](./configuration.md).
+
+For basic setup:
+
+```ruby
+# config/initializers/react_on_rails_pro.rb
+ReactOnRailsPro.configure do |config|
+  # Your configuration here
+  # See docs/configuration.md for all options
+end
+```
+
+# Node Package Installation
+
+**Note:** You only need to install the Node Package if you are using the standalone node renderer (`NodeRenderer`). If you're using `ExecJS` (the default), skip this section.
+
+## Install react-on-rails-pro-node-renderer
+
+### Using npm:
+
+```bash
+npm install react-on-rails-pro-node-renderer
+```
+
+### Using yarn:
+
+```bash
+yarn add react-on-rails-pro-node-renderer
+```
+
+### Add to package.json:
+
+```json
+{
+  "dependencies": {
+    "react-on-rails-pro-node-renderer": "^16.2.0"
+  }
+}
+```
+
+## Node Renderer Setup
+
+Create a JavaScript file to configure and launch the node renderer, for example `react-on-rails-pro-node-renderer.js`:
+
+```js
+const path = require('path');
+const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
+
+const env = process.env;
+
+const config = {
+  serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'),
+
+  // Listen at RENDERER_PORT env value or default port 3800
+  logLevel: env.RENDERER_LOG_LEVEL || 'debug', // show all logs
+
+  // Password for Rails <-> Node renderer communication
+  // See value in /config/initializers/react_on_rails_pro.rb
+  password: env.RENDERER_PASSWORD || 'changeme',
+
+  port: env.RENDERER_PORT || 3800,
+
+  // supportModules should be set to true to allow the server-bundle code to
+  // see require, exports, etc. (`false` is like the ExecJS behavior)
+  // This option is required to equal `true` in order to use loadable components
+  supportModules: true,
+
+  // workersCount defaults to the number of CPUs minus 1
+  workersCount: Number(env.NODE_RENDERER_CONCURRENCY || 3),
+
+  // Optional: Automatic worker restarting (for memory leak mitigation)
+  // allWorkersRestartInterval: 15, // minutes between restarting all workers
+  // delayBetweenIndividualWorkerRestarts: 2, // minutes between each worker restart
+  // gracefulWorkerRestartTimeout: undefined, // timeout for graceful worker restart; forces restart if worker stuck
+};
+
+// Renderer detects a total number of CPUs on virtual hostings like Heroku
+// or CircleCI instead of CPUs number allocated for current container. This
+// results in spawning many workers while only 1-2 of them really needed.
+if (env.CI) {
+  config.workersCount = 2;
+}
+
+reactOnRailsProNodeRenderer(config);
+```
+
+Add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "node-renderer": "node ./react-on-rails-pro-node-renderer.js"
+  }
+}
+```
+
+Start the renderer:
+
+```bash
+npm run node-renderer
+```
+
+## Rails Configuration for Node Renderer
+
+Configure Rails to use the remote node renderer:
+
+```ruby
+# config/initializers/react_on_rails_pro.rb
+ReactOnRailsPro.configure do |config|
+  config.server_renderer = "NodeRenderer"
+
+  # Configure renderer connection
+  config.renderer_url = ENV["REACT_RENDERER_URL"] || "http://localhost:3800"
+  config.renderer_password = ENV["RENDERER_PASSWORD"] || "changeme"
+
+  # Enable prerender caching (recommended)
+  config.prerender_caching = true
+end
+```
+
+### Configuration Options
+
+See [Rails Configuration Options](./configuration.md) for all available settings.
+
+Pay attention to:
+
+- `config.server_renderer = "NodeRenderer"` - Required to use node renderer
+- `config.renderer_url` - URL where your node renderer is running
+- `config.renderer_password` - Shared secret for authentication
+- `config.prerender_caching` - Enable caching (recommended)
+
+## Webpack Configuration
+
+Set your server bundle webpack configuration to use a target of `node` per the [Webpack docs](https://webpack.js.org/concepts/targets/#usage).
+
+## Additional Documentation
+
+- [Node Renderer Basics](./node-renderer/basics.md)
+- [Node Renderer JavaScript Configuration](./node-renderer/js-configuration.md)
+- [Rails Configuration Options](./configuration.md)
+- [Error Reporting and Tracing](./node-renderer/error-reporting-and-tracing.md)

data/docs/js-memory-leaks.md

@@ -0,0 +1,22 @@
+# JS Memory Leaks
+
+## Finding Memory Leaks
+For memory leaks, see [node-memwatch](https://github.com/marcominetti/node-memwatch). Use the `—inspect` flag to make and compare heap snapshots.
+
+## Causes of Memory Leaks
+
+
+### Mobx (mobx-react)
+
+```js
+import { useStaticRendering } from "mobx-react";
+
+const App = (props, railsContext) => {
+  const { location, serverSide } = railsContext;
+  const context = {};
+
+  useStaticRendering(true);
+```
+
+* See details here: [Mobx site](https://github.com/mobxjs/mobx-react#server-side-rendering-with-usestaticrendering)
+

data/docs/node-renderer/basics.md

@@ -0,0 +1,92 @@
+# Requirements
+
+- You must use React on Rails v11.0.7 or higher.
+
+# Install the Gem and the Node Module
+
+See [Installation](../installation.md).
+
+# Setup Node Renderer Server
+
+**node-renderer** is a standalone Node application to serve React SSR requests from a **Rails** client. You don't need any **Ruby** code to setup and launch it. You can configure with the command line or with a launch file.
+
+## Simple Command Line for node-renderer
+
+1. ENV values for the default config are (See [JS Configuration](./js-configuration.md) for more details):
+   - `RENDERER_PORT`
+   - `RENDERER_LOG_LEVEL`
+   - `RENDERER_BUNDLE_PATH`
+   - `RENDERER_WORKERS_COUNT`
+   - `RENDERER_PASSWORD`
+   - `RENDERER_ALL_WORKERS_RESTART_INTERVAL`
+   - `RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS`
+   - `RENDERER_SUPPORT_MODULES`
+2. Configure ENV values and run the command. Note, you can set port with args `-p <PORT>`. For example, assuming node-renderer is in your path:
+   ```
+   RENDERER_BUNDLE_PATH=/app/.node-renderer-bundles node-renderer
+   ```
+3. You can use a command line argument of `-p SOME_PORT` to override any ENV value for the PORT.
+
+## JavaScript Configuration File
+
+For the most control over the setup, create a JavaScript file to start the NodeRenderer.
+
+1. Create some project directory, let's say `renderer-app`:
+   ```sh
+   mkdir renderer-app
+   cd renderer-app
+   ```
+2. Make sure you have **Node.js** version **14** or higher and **Yarn** installed.
+3. Init node application and install the `react-on-rails-pro-node-renderer` package.
+   ```sh
+   yarn init
+   yarn add react-on-rails-pro-node-renderer
+   ```
+4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath:
+
+   ```javascript
+   import path from 'path';
+   import reactOnRailsProNodeRenderer from 'react-on-rails-pro-node-renderer';
+
+   const config = {
+     serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'),
+   };
+
+   reactOnRailsProNodeRenderer(config);
+   ```
+
+5. Now you can launch your renderer server with `node node-renderer.js`. You will probably add a script to your `package.json`.
+6. You can use a command line argument of `-p SOME_PORT` to override any configured or ENV value for the port.
+
+# Setup Rails Application
+
+Create `config/initializers/react_on_rails_pro.rb` and configure the **renderer server**. See configuration values in [Configuration](../configuration.md). Pay attention to:
+
+1. Set `config.server_renderer = "NodeRenderer"`
+2. Leave the default of `config.prerender_caching = true` and ensure your Rails cache is properly configured to handle the additional cache load.
+3. Configure values beginning with `renderer_`
+4. Use ENV values for values like `renderer_url` so that your deployed server is properly configured. If the ENV value is unset, the default for the renderer_url is `localhost:3800`.
+5. Here's a tiny example using mostly defaults:
+
+```ruby
+ReactOnRailsPro.configure do |config|
+ config.server_renderer = "NodeRenderer"
+
+ # when this ENV value is not defined, the local server at localhost:3800 is used
+ config.renderer_url = ENV["REACT_RENDERER_URL"]
+end
+```
+
+## Troublshooting
+
+- See [JS Memory Leaks](../js-memory-leaks.md).
+
+## Upgrading
+
+The NodeRenderer has a protocol version on both the Rails and Node sides. If the Rails server sends a protocol version that does not match the Node side, an error is returned. Ideally, you want to keep both the Rails and Node sides at the same version.
+
+## References
+
+- [Installation](../installation.md).
+- [Rails Options for node-renderer](../configuration.md)
+- [JS Options for node-renderer](./js-configuration.md)

data/docs/node-renderer/debugging.md

@@ -0,0 +1,38 @@
+Because the renderer communicates over a port to the server, you can start a renderer instance in this repo and hack on it.
+
+# Yalc vs Yarn Link
+The project is setup to use [yalc](https://github.com/whitecolor/yalc). This means that at the top level
+directory, `yalc publish` will send the node package files to the global yalc store. Running `yarn` in the 
+`/spec/dummy/client` directory will copy the files from the global yalc store over to the local `node_modules`
+directory.
+
+# Debugging the Node Renderer
+1. cd to the top level of the project.
+1. `yarn` to install any libraries.
+1. To compile renderer files on changes, open console and run `yarn build:dev`.
+1. Open another console tab and run `RENDERER_LOG_LEVEL=debug yarn start`
+1. Reload the browser page that causes the renderer issue. You can then update the JS code, and restart the `yarn start` to run the renderer with the new code.
+1. Be sure to restart the rails server if you change any ruby code in loaded gems.
+1. Note, the default setup for spec/dummy to reference the pro renderer is to use yalc, which may or may not be using a link, which means that you have to re-run yarn to get the files updated when changing the renderer.
+1. Check out the top level nps task `nps renderer.debug` and `spec/dummy/package.json` which has script `"node-renderer-debug"`.
+
+## Debugging using the Node debugger
+1. See [this article](https://github.com/shakacode/react_on_rails/issues/1196) on setting up the debugger.
+
+## Debugging Jest tests
+1. See [the Jest documentation](https://jestjs.io/docs/troubleshooting) for overall guidance.
+2. For RubyMine, see [the RubyMine documentation](https://www.jetbrains.com/help/ruby/running-unit-tests-on-jest.html) for the current information. The original [Testing With Jest in WebStorm](https://blog.jetbrains.com/webstorm/2018/10/testing-with-jest-in-webstorm/) post can be useful as well.
+
+# Debugging the Ruby gem
+
+Open the gemfile in the problematic app.
+
+```ruby
+gem "react_on_rails_pro", path: "../../../shakacode/react-on-rails/react_on_rails_pro"
+```
+
+Optionally, also specify react_on_rails to be local:
+
+```ruby
+gem "react_on_rails", path: "../../../shakacode/react-on-rails/react_on_rails"
+```

data/docs/node-renderer/error-reporting-and-tracing.md

@@ -0,0 +1,160 @@
+# Error Reporting and Tracing
+
+[Please see this documentation for versions before 4.0.0](https://github.com/shakacode/react_on_rails_pro/blob/ac2afba93c672f49f16bf967d6accbed0fda386e/docs/node-renderer/error-reporting-and-tracing.md).
+
+To integrate with error reporting and tracing services,
+you need a custom configuration script as described in [Node Renderer JavaScript Configuration](./js-configuration.md).
+
+It should initialize the services according to your requirements and then enable integrations.
+
+## Sentry
+
+1. [Set up Sentry](https://docs.sentry.io/platforms/javascript/guides/fastify/). You may create an `instrument.js` file as described there and require it in your configuration script, but it is simpler to call `Sentry.init` directly in your configuration script.
+2. Call `Sentry.init` with the desired options according to [the documentation](https://docs.sentry.io/platforms/javascript/guides/fastify/configuration/).
+3. Then load the integration:
+
+    ```js
+    require('react-on-rails-pro-node-renderer/integrations/sentry').init();
+   ```
+
+   - Use `react-on-rails-pro-node-renderer/integrations/sentry6` instead of `.../sentry` for versions of Sentry SDK older than 7.63.0.
+   - For Sentry SDK v8+ you can use `.init({ fastify: true })` to capture additional Fastify-related information.
+
+### Sentry Tracing
+
+To enable Sentry Tracing: 
+1. Include `enableTracing`, `tracesSampleRate`, or `tracesSampler` in your `Sentry.init` call. See [the Sentry documentation](https://docs.sentry.io/platforms/javascript/tracing/) for details, but ignore `Sentry.browserTracingIntegration()`.
+2. Depending on your Sentry SDK version: 
+    - if it is older than 7.63.0, install `@sentry/tracing` as well as `@sentry/node` (with the same exact version) and pass `integrations: [new Sentry.Integrations.Http({ tracing: true })]` to `Sentry.init`.
+    - for newer v7.x.y, pass `integrations: Sentry.autoDiscoverNodePerformanceMonitoringIntegrations()`.
+    - for v8.x.y, Node HTTP tracing is included by default.
+3. Pass `{ tracing: true }` to the `init` function of the integration. It can be combined with `fastify: true`.
+
+### Sentry Profiling
+
+[Follow this documentation](https://docs.sentry.io/platforms/javascript/guides/fastify/profiling/).
+
+## Honeybadger
+
+1. [Set up Honeybadger](https://docs.honeybadger.io/lib/javascript/integration/node/). Call `Honeybadger.configure` with the desired options in the configuration script.
+2. Then load the integration:
+
+    ```js
+    require('react-on-rails-pro-node-renderer/integrations/honeybadger').init();
+    ```
+
+    Use `init({ fastify: true })` to capture additional Fastify-related information.
+
+## Other services
+You can create your own integrations in the same way as the provided ones.
+If you have access to the React on Rails Pro repository,
+you can use [their implementations](https://github.com/shakacode/react_on_rails_pro/tree/master/packages/node-renderer/src/integrations) as examples.
+Import these functions from `react-on-rails-pro-node-renderer/integrations/api`:
+
+### Error reporting services
+
+- `addErrorNotifier` and `addMessageNotifier` tell React on Rails Pro how to report errors to your chosen service.
+- Use `addNotifier` if the service uses the same reporting function for both JavaScript `Error`s and string messages.
+
+For example, integrating with BugSnag can be as simple as
+```js
+const Bugsnag = require('@bugsnag/js');
+const { addNotifier } = require('react-on-rails-pro-node-renderer/integrations/api');
+
+Bugsnag.start({ /* your options */ });
+
+addNotifier((msg) => { Bugsnag.notify(msg); });
+```
+
+### Tracing services
+
+- `setupTracing` takes an object with two properties:
+  - `executor` should wrap an async function in the service's unit of work.
+  - Since the only units of work we currently track are rendering requests, the options to start them are specified in `startSsrRequestOptions`.
+
+To track requests as [sessions](https://docs.bugsnag.com/platforms/javascript/capturing-sessions/#startsession) in BugSnag 8.x+,
+the above example becomes
+```js
+const Bugsnag = require('@bugsnag/js');
+const { addNotifier, setupTracing } = require('react-on-rails-pro-node-renderer/integrations/api');
+
+Bugsnag.start({ /* your options */ });
+
+addNotifier((msg) => {
+  Bugsnag.notify(msg);
+});
+setupTracing({
+  executor: async (fn) => {
+    Bugsnag.startSession();
+    try {
+      return await fn();
+    } finally {
+      Bugsnag.pauseSession();
+    }
+  },
+});
+```
+
+You can optionally add `startSsrRequestOptions` property to capture the request data:
+
+```js
+setupTracing({
+  startSsrRequestOptions: ({ renderingRequest }) => ({ bugsnag: { renderingRequest } }),
+  executor: async (fn, { bugsnag }) => {
+    Bugsnag.startSession();
+    // bugsnag will look like { renderingRequest }
+    Bugsnag.leaveBreadcrumb('SSR request', bugsnag, 'request');
+    try {
+      return await fn();
+    } finally {
+      Bugsnag.pauseSession();
+    }
+  },
+});
+```
+
+Bugsnag v7 is a bit more complicated:
+
+```js
+const Bugsnag = require('@bugsnag/js');
+const { addNotifier, setupTracing } = require('react-on-rails-pro-node-renderer/integrations/api');
+
+Bugsnag.start({ /* your options */ });
+
+addNotifier((msg, { bugsnag = Bugsnag }) => {
+  bugsnag.notify(msg);
+});
+setupTracing({
+  executor: async (fn) => {
+    const bugsnag = Bugsnag.startSession();
+    try {
+      return await fn({ bugsnag });
+    } finally {
+      bugsnag.pauseSession();
+    }
+  },
+});
+```
+
+### Fastify integrations
+
+If you want to report HTTP requests from Fastify, you can use `configureFastify` to add hooks or plugins as necessary.
+Extending the above example:
+
+```js
+const { configureFastify } = require('react-on-rails-pro-node-renderer/integrations/api');
+
+configureFastify((app) => {
+  app.addHook('onError', (_req, _reply, error, done) => {
+    Bugsnag.notify(error);
+    done();
+  });
+});
+```
+
+You could also treat Fastify requests as sessions
+using [onRequest](https://fastify.dev/docs/latest/Reference/Hooks/#onrequest)
+or [preHandler](https://fastify.dev/docs/latest/Reference/Hooks/#prehandler) hooks.
+
+It isn't recommended to use the [fastify-bugsnag](https://github.com/ZigaStrgar/fastify-bugsnag) plugin
+since it wants to start Bugsnag on its own.