Skip to main content
Edit

Node Renderer Debugging

Pro Feature — Available with React on Rails Pro. Free or very low cost for startups and small companies. Upgrade or licensing details →

Because the renderer communicates over a port to the server, you can start a renderer instance locally in your application and debug it.

Monorepo Workflow​

For renderer debugging inside this repo, use the Pro dummy app at react_on_rails_pro/spec/dummy. It is a pnpm workspace app and already points at the local packages in this monorepo.

Debugging the Node Renderer​

Quick start: debugging with the full stack running​

If you already have the dummy app running via bin/dev (which uses Procfile.dev), the node renderer is listening on port 3800 but without --inspect. To attach a debugger you first need to restart it with --inspect — either stop the renderer process and run pnpm run node-renderer:debug, or temporarily add --inspect to the node-renderer: entry in Procfile.dev and overmind restart node-renderer. Then:

  1. Open chrome://inspect in Chrome and connect to the renderer process.
  2. Use overmind to isolate renderer logs: overmind connect node-renderer (Ctrl-B to detach).
  3. After a code change, restart just the renderer: overmind restart node-renderer.

Isolated debugging: manual per-terminal startup​

Use this when you need full control over the renderer process — different flags, a specific bundle, or rebuilding just the renderer package.

  1. From the repo root, install dependencies and build the local packages: 
    pnpm install
    pnpm run build
  2. In one terminal, start the Pro dummy bundle watcher: 
    cd react_on_rails_pro/spec/dummy
    pnpm run build:dev:watch
  3. In another terminal, start the renderer with verbose logging: 
    cd react_on_rails_pro/spec/dummy
    RENDERER_LOG_LEVEL=debug pnpm run node-renderer
  4. If you want to attach a debugger instead, run: 
    cd react_on_rails_pro/spec/dummy
    pnpm run node-renderer:debug
  5. Reload the page that triggers the SSR issue and reproduce the problem.
  6. If you change Ruby code in loaded gems, restart the Rails server.
  7. If you change code under packages/react-on-rails-pro-node-renderer, rebuild that package before restarting the renderer: 
    pnpm --filter react-on-rails-pro-node-renderer run build
  8. If you are debugging an external app instead of the monorepo dummy app, refresh the installed renderer package using your local package workflow (for example yalc, npm pack, or a workspace link) before rerunning the renderer.

Debugging Memory Leaks​

If worker memory grows over time, use heap snapshots to find the source.

Quick approach: --heapsnapshot-signal (no code changes)​

Use Node's built-in flag to write heap snapshots on demand:

cd react_on_rails_pro/spec/dummy
# Adjust the port if your Rails app points at a different renderer URL.
NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node renderer/node-renderer.js

Then capture snapshots at different times:

kill -USR2 <worker-pid>   # writes a .heapsnapshot file to the working directory

This also works in production containers — set NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" as an environment variable, send the signal at different times, then copy the .heapsnapshot files to your local machine for analysis.

Detailed approach: with forced GC​

For more precise results, start the renderer with --expose-gc and a custom signal handler that forces garbage collection before each snapshot. See the Memory Leaks guide for the code.

Analyzing snapshots​

  1. Load both .heapsnapshot files in Chrome DevTools (Memory tab → Load).
  2. Use the Comparison view to see which objects accumulated between snapshots.
  3. Look for growing string, Object, and Array counts — these typically point to module-level caches.

Isolating memory issues with a separate renderer workload​

When diagnosing memory leaks in a containerized environment, running the Node renderer as a separate workload (instead of a sidecar) makes it easier to:

  • Monitor Node memory independently from Rails
  • Capture heap snapshots without affecting the Rails process
  • Restart or scale the renderer without restarting Rails

See the Memory Leaks guide for common patterns and fixes.

Debugging using the Node debugger​

  1. See this article on setting up the debugger.

Debugging Jest tests​

  1. See the Jest documentation for overall guidance.
  2. For JetBrains IDEs, see the RubyMine documentation for current instructions.

Debugging the Ruby gem​

Open the gemfile in the problematic app.

gem "react_on_rails_pro", path: "../../../shakacode/react-on-rails/react_on_rails_pro"

Optionally, also specify react_on_rails to be local:

gem "react_on_rails", path: "../../../shakacode/react-on-rails/react_on_rails"