Laravel Laravel Package

Getting Started

• Install the package with Composer and follow the README setup for the frontend/SSR entry point, published config, and any required build step. Look first at the README, the Rsc facade, the package config, and any example route/controller.
• The first useful use case is returning an RSC page from a Laravel route/controller using the package’s normal render path, e.g. return Rsc::render('Dashboard', ['user' => $request->user()]);.
• v0.15.5 adds Rsc::refuse(), which lets a server-side page/component refuse normal rendering while carrying structured data for the page. Start by adding one guarded branch — a policy check, feature flag, or tenant check — and confirm the frontend handles the refusal payload.

Implementation Patterns

• Use Rsc::refuse($data) as an explicit page-level control-flow branch, not as an exception replacement:

  if (! $user->can('view-dashboard')) {
      return Rsc::refuse([
          'reason' => 'forbidden',
          'message' => 'You do not have access to this dashboard.',
      ]);
  }
  
  return Rsc::render('Dashboard', ['user' => $user]);
  

• Keep refusal payloads small, stable, and JSON-serializable. Prefer a consistent shape such as reason, message, and optional data, and centralize it in an enum, DTO, or helper so frontend and backend agree.

• Good day-to-day uses: authorization failures, feature-flag gates, onboarding/verification gates, unsupported tenant states, maintenance/read-only modes, and “not ready yet” page states that need data rather than a redirect.

• Compose with Laravel’s normal request validation and policies before rendering. Let validation errors stay as validation errors; use Rsc::refuse() for page-render decisions.

• Test both branches: a feature test for the normal RSC response and one for the refusal payload. Add a frontend/e2e check that the page actually renders the refusal state rather than a blank screen.

Gotchas and Tips

• Rsc::refuse() is not an exception. Middleware and Laravel’s exception handler will not automatically catch it unless the package wires that up; return it explicitly from the controller/action.
• Do not put secrets, raw Eloquent models, closures, or un-serializable objects in the refusal payload. Treat it as data sent to the client.
• Confirm the HTTP status and caching behavior your app expects. If the refusal represents a 403, verify whether the package sets that status or whether you need middleware/response adjustment.
• The frontend must know how to handle refusals. A new backend refusal branch without a matching client state can produce a broken or blank page.
• v0.15.5 is a minor release, but pin/update dependencies deliberately and rebuild frontend assets after upgrading. Check that the JS/SSR side is compatible with the PHP package version.
• Debug refusals by inspecting the RSC response/network payload and logging the refusal reason — not the full payload if it may contain user data.