Detect unsupported client-hook usage in RSC/server bundle earlier and fail with actionable diagnostics

[justin808]

Context

While building the Hacker News demo at https://github.com/shakacode/react_on_rails-hacker-news-app with React on Rails Pro RSC, we hit a very specific but realistic failure mode:

• a component used useState
• the component was expected to behave as a client boundary
• it still ended up executing in the wrong runtime
• the app failed at render time instead of failing earlier with an actionable explanation

The concrete runtime error was:

useState is not a function

Problem

This class of mistake is easy to make in a real Rails app, especially when migrating an existing codebase or mixing traditional SSR mental models with RSC mental models.

The current failure mode is too late and too indirect. By the time the developer sees the problem, they are already debugging a broken stream/render instead of getting told:

• this component uses client hooks
• it is being treated as a server component / wrong runtime component
• here is the file that needs a client boundary fix

Requested improvement

Add earlier and more actionable diagnostics for unsupported client-hook usage in the wrong runtime. Possible options:

• compile-time diagnostics where feasible
• startup-time validation of registered components / boundaries
• explicit runtime messaging that names the component and file
• guidance in the error message about supported client-boundary patterns in React on Rails Pro

Related

Issue #3076 covered documentation pitfalls around 'use client' classification in another app. This issue is about product/runtime diagnostics so the mistake is caught earlier and explained more clearly.