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 already listening on port 3800 with --inspect enabled. To debug:

  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:

  1. Start the renderer with --expose-gc to enable forced GC before snapshots: 
    cd react_on_rails_pro/spec/dummy
    # Adjust the port if your Rails app points at a different renderer URL.
    RENDERER_PORT=3800 node --expose-gc client/node-renderer.js
  2. Take heap snapshots at different times using v8.writeHeapSnapshot() (triggered via SIGUSR2 signal or a custom endpoint).
  3. Load both snapshots in Chrome DevTools (Memory tab → Load) and use the Comparison view to see which objects accumulated between snapshots.
  4. Look for growing string, Object, and Array counts — these typically point to module-level caches.

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 RubyMine, see the RubyMine documentation for the current information. The original Testing With Jest in WebStorm post can be useful as well.

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"