rails ruact:doctor

rails ruact:doctor is a diagnostic task that checks your ruact installation and reports ✓/✗ for each requirement.

Usage

rails ruact:doctor

Run it after installation, after upgrading the gem, or whenever something is not working as expected.

What it checks

The doctor runs 6 checks in order:

1. Manifest

Verifies that public/react-client-manifest.json exists (or the path configured via config.manifest_path).

✓ Manifest found at /your/app/public/react-client-manifest.json
✗ Manifest not found — run vite build

Fix: Run npm run build (production) or npm run dev (development, which generates the manifest automatically).

2. Vite

Attempts a TCP connection to localhost:5173 to verify the Vite dev server is accessible.

✓ Vite accessible at localhost:5173
✗ Vite not accessible at localhost:5173 — run npm run dev

Fix: Start the Vite dev server with npm run dev or bin/dev. In production, this check is informational — Vite does not run in production.

3. Controller

Checks that app/controllers/application_controller.rb includes Ruact::Controller.

✓ Ruact::Controller included in ApplicationController
✗ Ruact::Controller not included in ApplicationController

Fix: Add include Ruact::Controller to ApplicationController:

class ApplicationController < ActionController::Base
  include Ruact::Controller
end

4. Layout

Checks that app/views/layouts/application.html.erb contains the Rails RSC root marker.

✓ React shell present in application.html.erb
✗ React shell missing from application.html.erb

Fix: Run the install generator to add the required layout:

rails generate ruact:install

5. Streaming

Reports the current streaming mode and the detected web server.

✓ streaming: buffered (Puma)
✓ streaming: enabled (Puma)

This check always passes — it is informational. enabled means ActionController::Live is included and progressive streaming is active. buffered means the full payload is sent at once (still correct, but no progressive Suspense).

6. Legacy constant scan

Scans config/initializers/**/*.rb and app/**/*.rb for any reference to the pre-rename gem name (regex form rails[_-]rsc) or its PascalCase constant equivalent. The gem went through a rails[_-]rsc → ruact rename between v0.0.2 and v0.0.3; a leftover reference here means a host-side migration was incomplete. When something is found, the doctor prints the exact offending string (built from fragments at runtime; see gem/lib/ruact/doctor.rb constants LEGACY_CONST and LEGACY_GEM) plus the file path and line number, so you can jump to the call site and fix it.

When all references are clear, you see a ✓ No legacy … references found line. Otherwise each hit is printed with a ✗ prefix and the source location.

Fix: replace the legacy constant prefix with Ruact (matching Ruact::Controller, Ruact::Serializable, and friends), and update the Gemfile to require gem "ruact". See the Renamed section in CHANGELOG for the full migration table.

Exit behaviour

If all 6 checks pass, ruact:doctor exits 0. If any check fails:

Each failure is printed with ✗
A hint is printed: Run rails generate ruact:install to fix configuration issues
The task exits with a non-zero status (can be used in CI)

Running in CI

- name: Check ruact installation
  run: bundle exec rails ruact:doctor

This catches misconfigured installations before they reach production.

Running programmatically

The doctor is implemented as Ruact::Doctor — extracted from the Rake task for direct testability:

passed = Ruact::Doctor.run
# prints ✓/✗ for each check, returns true if all pass