Realtime Compiler Laravel Package

Technical Evaluation

Architecture fit. HydePHP is a Laravel-based static site generator; hyde/realtime-compiler is a companion server that resolves Hyde routes and renders pages on demand instead of requiring a full static build for every preview. Architecturally this is the most important fact about the package: it is a development/preview-time tool, not a production runtime component. It does not sit in the request path of anything we ship to customers, does not persist data, and does not own an SLO. For a Laravel shop the mental model is familiar — Composer package, service provider, Blade rendering — so conceptual fit is high even though adoption is near zero.

Integration feasibility. Mechanically trivial: a Composer require-dev, a version constraint against the Hyde core we already run, and an Artisan invocation. There is no data migration, no infrastructure provisioning, no auth surface, and no CI/CD rework required to try it. Feasibility is therefore gated almost entirely by version-matrix compatibility and by whether the realtime output faithfully matches the built output.

Technical risk. Low blast radius, high uncertainty. Low blast radius because a dev-only tool failing means a developer falls back to hyde build and a static server. High uncertainty because the signals are weak: 2 stars, 0 dependents, a single-vendor ecosystem, and a release cadence we cannot infer maturity from. The two risks that actually matter are (1) preview/build divergence — realtime rendering that differs subtly from the static build erodes trust in previews and produces "works in dev, wrong in prod" content bugs, and (2) version coupling — the package tracking Hyde core loosely enough that a core upgrade silently breaks local dev.

Key questions.

• Is this maintained by the Hyde core team and released in lockstep with core, or is it a side project?
• What are the supported PHP/Laravel/Hyde version ranges, and how tight is the constraint?
• Does realtime route resolution use the same pipeline as the static build, and is there a documented fidelity guarantee?
• Is it explicitly dev-only, or is it intended to back ephemeral PR preview environments?
• What is the supported fallback if the package is abandoned mid-cycle?
• License and contribution model — can we patch it internally if needed?

Integration Approach

Stack fit. Native Laravel/PHP. It installs as a require-dev package into an existing Hyde site repository and is driven from the CLI alongside the current hyde build / hyde serve commands. No new language, runtime, or container is introduced.

Migration path. There is no migration. Existing content, Blade views, Markdown, and the static build pipeline stay untouched. The compiler is additive: it becomes an alternative local preview command while hyde build remains the canonical artifact producer. The only artifact we should produce from this evaluation is a one-page "how to preview locally" note for the docs/content team.

Compatibility. Pin the package to a narrow range that matches our Hyde core version and re-validate on every Hyde upgrade. Because there are zero dependents, we are effectively the first real adopter — we should assume no one else has exercised our exact version combination. Verify PHP version support explicitly rather than inferring it from composer.json alone.

Sequencing.

1. Spike on a single low-stakes Hyde site in a branch; do not touch shared tooling.
2. Run a fidelity check: render a representative sample of pages (nested routes, collections, custom Blade, media) through both the realtime compiler and the static build, and diff the HTML.
3. If fidelity holds, document it as an optional local dev convenience and add it to onboarding.
4. Only then evaluate ephemeral preview environments — and treat that as a separate decision with its own risk review.
5. Explicitly forbid it from any production or customer-facing deploy path in the platform standards doc.

Operational Impact

Maintenance. Near-zero steady-state cost: it is a dev dependency with no runtime footprint, no secrets, and no observability requirement. The recurring cost is version-bump friction whenever Hyde core advances — budget a small quarterly compatibility check owned by the platform/docs team rather than leaving it to individual developers.

Support. Community-only via GitHub issues; no commercial backing, no SLA, and documentation will be thin at this adoption level. Assume engineers will read the source. Internal ownership should sit with the team that owns the docs site, not with application teams, so there is exactly one accountable party.

Scaling. Irrelevant at production scale. The only scaling dimensions are local dev server responsiveness on large content sets and, if we ever use it for previews, the cost of standing up per-branch environments — which we should avoid until fidelity is proven.

Failure modes.

• Hyde upgrade breaks the compiler — local dev annoyance only; fallback to static build is immediate and well understood.
• Preview diverges from build — the most damaging failure because it is silent and produces misplaced confidence; mitigated by the fidelity check and by keeping hyde build as the source of truth.
• Upstream abandonment — we end up pinned to an ageing Hyde core or fork the package; acceptable given it is disposable tooling.
• Scope creep into production serving — the only failure mode that could actually hurt; mitigated by policy, not technology.

Ramp-up. Very low for anyone already writing Laravel or Hyde content — roughly an hour to first successful preview. The real ramp-up cost is not learning the tool but learning to distrust it appropriately: developers must internalize that "it renders in realtime" is not evidence the static build is correct. Given the modest benefit (faster content iteration) against the negligible cost and negligible risk, this is a reasonable try-and-keep-or-drop candidate rather than a strategic dependency.