Laravel Laravel Package

Technical Evaluation

Architecture fit rsc-kit/laravel sits at the seam between Laravel's request/controller layer and a React Server Components renderer, so adopting it is an architectural decision, not a library swap. The v0.15.5 addition — Rsc::refuse(), a refusal carrying data for the page — is the first primitive in this package that lets server-side logic authoritatively decline to render a component and hand structured data back to the client. That matters to a TPM because it is the mechanism by which authorization, feature-flagging, and "not available in your region"-style branching can live in PHP rather than leaking into the JS bundle or being duplicated on both sides. If your product has any server-authoritative UI decisions (entitlements, per-tenant configuration, A/B assignment), this is the right shape of API. If it does not, this release is not a reason to adopt the package.

Integration feasibility Feasible but non-trivial: RSC in a PHP host implies a second runtime (Node) alongside PHP-FPM, a bundler step (Vite) that must stay in lockstep with the PHP-side component registry, and a serialization contract between the two. Rsc::refuse() deepens that contract because refusal payloads cross the boundary and must be deserializable on the client with a stable shape. There is no evidence in the release notes of a coordinated JS-side handler API, protocol versioning, or a documented serialization format — those are the first things to verify in the spike.

Technical risk

• Pre-1.0 surface. v0.15.x means the refusal signature and semantics are not frozen; a 0.16 rename is plausible and would be a breaking change for us.
• Bus factor. The release is authored by a single contributor in a small org. No signals here about maintainer depth, release cadence, or security policy.
• Boundary failure modes are opaque. A refusal that fails to serialize mid-stream is a hard-to-diagnose class of bug (blank page, partial hydration) with no obvious Laravel-side stack trace.
• Interaction with streaming/Suspense. Refusal presumably short-circuits rendering; whether it composes correctly with Suspense boundaries and error boundaries is unverified.
• Skill scarcity. RSC mental models are not common on PHP teams; the risk lands on ramp-up, not on the code.

Key questions

1. Is there a matching client-side API to receive a refusal, and is it shipped in this release or a paired JS package?
2. What is the serialization format, and is it versioned/negotiated between PHP and JS?
3. Does refuse() abort the stream, and how does that interact with Suspense and error boundaries?
4. What is the project's stated stability policy between 0.15 and 1.0 — deprecation windows, changelog discipline, semver intent?
5. How do refusals interact with Laravel middleware, auth guards, and policies — is the refusal evaluated after authorization, or does it replace it?
6. Who else is running this in production, and at what scale?

Integration Approach

Stack fit Reasonable only if the team already runs a Node toolchain for frontend builds — which most Laravel shops do via Vite — and is comfortable operating a Node process in production. The package does not remove PHP from the request path, so you carry both runtimes and both dependency graphs permanently. Treat it as a frontend-architecture commitment, not a Composer dependency.

Migration path Do not attempt an incremental page-by-page migration of an existing Blade/Livewire/Inertia app. RSC integration is a routing-and-rendering-model decision; partial adoption creates two rendering paradigms with a shared layout and divergent data-loading idioms. The viable path is a bounded, additive surface: one new route group or one new product area built RSC-first, coexisting with the existing app behind the same session/auth layer.

Compatibility Pin exactly (0.15.5, not ^0.15) and vendor the lockfile. Verify the paired JS package version explicitly — the PHP/JS version pairing is the most likely source of silent breakage. Confirm PHP and Laravel minor-version support in the package's CI matrix before committing; the notes do not state it.

Sequencing

1. Spike (1–2 weeks). One page, one server-side authorization decision expressed as a refusal, one client-side handler. Success criteria: refusal payload round-trips, fails loudly when malformed, and is observable in logs.
2. Contract freeze. Document our internal wrapper around refuse() so a 0.16 rename is a one-file change. Do not call the package API directly from feature code.
3. Single production surface. Ship one low-blast-radius area behind a flag; instrument refusal frequency and hydration errors.
4. Expand only after 1.0 or after two clean minor upgrades. Treat 0.x minor bumps as potential breaking changes in the upgrade calendar.

Operational Impact

Maintenance Two dependency graphs to patch, two lockfiles to audit, and a PHP/JS version pairing that must move together. Budget recurring maintenance for the wrapper layer and for tracking upstream releases; a solo-maintainer pre-1.0 package will not absorb your upgrade burden. Assign explicit ownership of the PHP↔JS version pin.

Support No commercial support path is evident. Internal escalation means reading the renderer source. Ensure at least one engineer can debug inside both the Laravel package and the JS renderer — that is a single point of failure if it is one person.

Scaling The PHP tier scales conventionally. The Node render tier does not: it needs its own horizontal scaling, its own concurrency limits, and its own cold-start story. Refusals are cheap (they short-circuit work) but they add a code path that bypasses normal render metrics, so dashboards will undercount traffic unless refusal outcomes are emitted as first-class events.

Failure modes

• Malformed or unversioned refusal payload → client receives data it cannot handle; symptom is a blank region, not a 500.
• Node renderer unavailable → PHP returns 200 with a broken page unless you add a health check and a fallback path.
• Partial stream termination on refusal mid-render → truncated HTML, hydration mismatch, silent client errors.
• Silent API drift on a 0.15 → 0.16 upgrade → refusals stop being honored with no compile-time signal. Mitigations: schema-validate refusal payloads on both sides, add an explicit renderer health check, and write a contract test that asserts refusal round-trip on every upgrade.

Ramp-up Expect 2–4 weeks before a mid-level Laravel engineer is productive and considerably longer before they can debug the boundary. The concepts to teach are not in the package docs: RSC's server/client split, the serialization contract, and the refusal-as-control-flow idiom. Onboarding material should be written internally — do not assume upstream documentation covers the refusal path, since the feature shipped without it in these notes.