Nova Iframe Laravel Package

Technical Evaluation

Architecture fit. The package is a thin Nova field that renders an iframe — roughly 50 lines of PHP plus a compiled Vue asset. It sits entirely in the presentation layer of the Nova admin: no migrations, no service providers with side effects, no data model, no queue or event surface. That is a good architectural shape for what it does. It also means the package is not an integration layer — it cannot propagate sessions, authenticate against the target, transform data, or handle write-back. Any workflow that needs those things must be built outside the package and will not be helped by adopting it.

Fit should be judged against the workflow, not the code: does embedding a read-only dashboard, provider console, status page, or PDF preview inside a resource detail view measurably reduce context switching for operators? The iframe is incidental; the consolidation bet is the real decision.

Integration feasibility. Low-effort and additive. The realistic path is: read vendor/metrixinfo/nova-iframe/composer.json to confirm the laravel/nova constraint matches our Nova major, verify the actual class name/namespace in src/ (micro-package READMEs are routinely stale on casing), then add a single field to one resource's fields(). Rollback is deleting one line. Nothing here touches the database, so there is no migration or data-integrity risk.

The real feasibility gate is external and non-negotiable: the target origin must permit framing. curl -sI <target> | grep -iE 'x-frame-options|content-security-policy' returns DENY or SAMEORIGIN, the package cannot help, and no amount of Nova work will fix it. Run that check before scheduling engineering work. The second gate is our own CSP frame-src allowlist — a deployment-config change that must land in the same PR or the feature will appear broken.

Technical risk. Concentrated, small, and mostly outside the package:

• Supply-chain / abandonment. 7 stars, 0 dependents, single maintainer, no evident CI or changelog. Probability of unannounced breakage across Nova majors is high; blast radius is low because the code is tiny and forkable.
• Nova major compatibility. Nova 4 moved to Vue 3 and changed asset registration. A package at this adoption level has almost certainly not tracked that. Grep the compiled bundle for new Vue / Vue.component; if present, it will not register on Nova 4+ and the inline rebuild is the correct answer.
• Security posture of the field itself. sandbox, allow, and referrerpolicy are likely unset. If the URL derives from record data, an unescaped src binding is an injection vector. These are our review deliverables regardless of vendor.
• Content risk. Mixed http:// content silently blocked in an HTTPS admin; javascript:/data: schemes if URLs come from user-supplied slugs.
• Operational risk in index views. An iframe per row fires N third-party requests per page load and will visibly degrade the admin. This is a usage-discipline risk we control, not a vendor risk.

Key questions to resolve before commitment:

1. Which Nova major are we on, and does the package's laravel/nova constraint actually admit it?
2. Does the target origin permit framing, and who owns the frame-src CSP change?
3. Is the embedded content read-only or independently authenticated? If it needs our session cookie, the iframe is the wrong mechanism — use a short-lived signed URL or route to API/JS integration.
4. What is the measured win (time-to-answer, context switches, handle time), and against which baseline?
5. Adopt-and-pin, fork as first-party field (~1–2 engineer-days), or link-out in a new tab (zero dependency, zero CSP work)? Decide now, not after the pilot.
6. Who is the named internal owner?

Integration Approach

Stack fit. Requires an existing Laravel + Nova admin. It is a presentation-only dependency with no runtime footprint in the application proper. It fits cleanly if and only if the use case is display-only: resource detail views, or a dashboard card. It explicitly does not fit create/update form interactivity — iframes serialize nothing into form state — nor SSO/session propagation, deep-linked authenticated tools, or high-availability operator surfaces. Route those to API or JS integrations.

Migration path. There is no migration. The package is additive, and the reversal is a one-line deletion from fields(). The migration work that does exist is around it: adding the origin to frame-src, deciding an allowlist policy, and building URL construction on the model rather than in fields() so it is testable and can fail closed. Treat the package as a scaffold for a first-party field rather than a long-term dependency; the honest framing is "borrow the reference implementation, own the outcome."

Compatibility. Two compatibility axes, both cheap to check and both blocking:

• Nova/Laravel major — read the constraint in composer.json first; five seconds tells you whether the field registers at all. Then confirm the compiled bundle is not Vue 2 if we are on Nova 4+.
• Browser/CSP — target X-Frame-Options, target frame-ancestors, and our own frame-src all must align. This is deployment configuration, not package configuration, and it is the most common source of "the package is broken" tickets when the package is fine.

The realistic long-term compatibility plan is a fork. Extending the field and swapping the Vue component (component(): string returning our own registered component) is a one-to-two-day job because the underlying package is ~50 lines. Budget that up front rather than discovering it during a Nova upgrade.

Sequencing.

1. Spike (hours). curl the target headers; read composer.json; grep the bundle for sandbox/allow/url/height and for Vue 2 idioms. Output: go / no-go / fork-now.
2. Decision gate. Compare adopt-and-pin vs. fork vs. link-out on equal footing, with the fallback priced before the pilot so it never becomes a sunk-cost argument.
3. Policy PR. CSP frame-src allowlist, sandbox attributes, allowlist validation in the URL builder. This lands with the feature, not after.
4. Pilot. One resource, detail view only, onlyOnDetail() + hideFromIndex(), behind a feature flag. Visible fallback link shipped in the same change.
5. Measure and decide. Instrument against the pre-agreed metric. Either promote to a second resource or roll back the one line.
6. Harden. Pin exact version, commit composer.lock, add one feature/Dusk test asserting the detail page contains the expected src, name an owner in an ADR.

Operational Impact

Maintenance. Low absolute effort, non-zero and lumpy. Budget roughly half a day per Nova major for re-validation, plus whatever the CSP allowlist review costs annually. The single-maintainer, 7-star profile means we should assume we are the maintenance path: pin the exact constraint (1.0.* or tighter), commit composer.lock, and treat any upstream commit as unreviewed until read. If the package doesn't auto-register its compiled asset, register it ourselves via Nova::serving() — that is a small piece of glue we now own permanently.

Support. The support surface is operator-facing and predictable, and most of it is not the package's fault. Expect "blank box" reports. Triage in a fixed order: devtools console for X-Frame-Options / frame-src violations, network tab to confirm the request was issued at all, then curl -sI on the target. Publish that triage as a runbook so tier-one doesn't escalate to engineering. Also publish the escape hatch: an embed failure must never block an operator from completing the task, so every embed ships with a visible "open in new tab" affordance.

Scaling. Two distinct scaling concerns:

• Admin performance. Scale is per-page-load, not per-user. One iframe on a detail view is fine; an iframe on an index column multiplies third-party requests by row count and degrades the admin for everyone. Enforce onlyOnDetail() + hideFromIndex() as a code-review rule, not a preference. If we embed in a custom tool that reuses component instances across records, bind :key to the record ID so frames remount instead of showing stale content.
• Content scaling. Third-party dashboards are sized for full viewports. Fixed pixel heights (400px iframe, 900px dashboard) are the most common review complaint and will generate tickets as the roster of embedded tools grows. Set height per field, and if the component hard-codes it, wrap or fork and emit a class or responsive style.

Failure modes. Ranked by likelihood and cost:

Ramp-up. Effectively zero for a Laravel developer — one field declaration. The learning is not the API; it is the operating constraints: iframes don't participate in form state, don't carry the Nova session cross-origin, and are governed by CSP and X-Frame-Options at both ends. Onboarding should cover the CSP allowlist policy, the blank-frame triage order, the detail-view-only rule, and the sandbox attribute policy (never allow-scripts + allow-same-origin together on untrusted origins). One named owner, one ADR, one test, one runbook — that is the entire operational package, and it outlives the dependency.