padocia/laravel-nova-pdf
Laravel Nova PDF adds PDF handling to Nova resources, letting you generate, preview, and download PDF documents from your admin panel using familiar Laravel and Blade workflows.
Architecture fit. The package is a thin Nova-side wrapper — a Nova Action that collects model data, renders a Blade view, pipes the HTML through Browsershot::html(), and returns a streamed download. That is the correct seam for the problem it solves: PDF export is a presentation concern bolted onto an existing resource, not a domain capability. Critically, the architecture is not what the name implies. There is no PHP-native renderer here; the actual rendering engine is headless Chromium via Node/Puppeteer. Any evaluation that treats this as "a Composer dependency" is wrong by an order of magnitude — it is a Composer dependency plus a Node runtime plus a pinned Chrome binary. For a team already operating headless Chrome (screenshots, reporting, e2e test infrastructure), the marginal architectural cost is near zero and the fit is good. For a team that is not, the fit is poor: an admin export button would silently acquire ownership of a browser runtime.
Integration feasibility. Mechanically trivial to install (composer require + vendor publish for config and Blade views) and trivially small to read end to end — the src/Actions/ directory is the whole story. The first-use validation is a single afternoon: add the action to one resource's actions(), open a record, run it, confirm bytes come out. That one test simultaneously validates Nova registration, template resolution, Chromium launch, and the response path. The real feasibility question is not installation but environment: node -v, npm -v, which chromium, npx puppeteer browsers list on the exact production image. If that fails, nothing else in this assessment matters.
Technical risk. Ranked, because they are not equivalent:
spatie/browsershot against it will either fail install or blow up at runtime — the html(), path-setter, and option-name APIs have changed. Pin the package, pin Browsershot, pin the Chromium image, and treat an unpinned transitive bump as an incident.--no-sandbox, which is a genuine security downgrade: an unsandboxed Chromium rendering admin-influenced HTML can reach file://, localhost services, and cloud metadata endpoints. This is a design-level concern, not a footnote — mitigate with base64-embedded assets, no user-controlled URLs in templates, and a network-scoped render worker.handleBrowsershotOptions" — meaning a real option-plumbing bug reached a tagged release. Every option we depend on (format, margins, waitUntil, timeout, node/chrome paths) must be verified against a template with known measurements, not trusted from the config file.1.0.x revival. We are the QA. composer audit plus a Chrome/Puppeteer CVE scan belongs in the install gate.Key questions. (a) Do we already run headless Chromium anywhere in production, and if not, who owns that runtime? (b) Is our Nova major version compatible — verified by running an action, not by reading the README? (c) Does this need to scale past single-record, on-demand export (batch billing, nightly statements), which the synchronous synchronous design does not support? (d) Do rendered PDFs need to persist — and if yes, what is the retention policy that governs the signed-URL expiry? (e) Is the output internal-only, or will it be cited as the foundation for customer-facing invoices? That boundary should be drawn before, not after, someone demos it.
Stack fit. The pattern — Nova Action → Blade view → server-side HTML→PDF → download — is a clean fit for any Laravel/Nova stack. The package itself is a ~150-line reference implementation of that pattern. The strategic recommendation is therefore to own the seam, not the dependency: define an internal PdfRenderer interface (render(string $view, array $data): string) immediately, and have the Nova action call that interface rather than the package API. This costs an hour and buys the ability to swap to dompdf, queue the render, inject test fixtures, or fork the whole thing without touching the controller layer. Given the maturity profile, that insulation is not optional.
Migration path. Two viable routes, and the decision should be explicit:
PdfRenderer interface and subclass the action for per-resource customization. If Nova compatibility fatals (the likely case on Nova 4/5), fall back to Route B — the read was still worth it.src/Actions/* in an afternoon and write our own action wrapping Browsershot::html() directly. We end up owning this code regardless; the only question is whether we paid to discover that now or in six months when the package is unmaintained and blocking a Nova upgrade.Either route lands in the same place architecturally. Route A is faster to a demo; Route B is faster to a stable production artifact.
Compatibility. Pin aggressively: the package, spatie/browsershot, the Chromium image version, and the Node major. Verify the container has the specific fonts the templates use — slim base images ship almost none, and Chromium substitutes silently, so layout drift will not surface as an error. Verify waitUntilNetworkIdle() (or the pinned version's equivalent) if templates reference remote assets; missing logos and background graphics are a wait-condition bug, not a rendering bug.
Sequencing. Deliberately staged, cheapest-risk-first:
PdfRenderer abstraction in place before the second template exists.resources/views/pdf/<domain>/<variant>.blade.php. Pass a flattened view-model array (formatted currency, precomputed totals, absolute image URLs, string dates), never the Eloquent model, or Browsershot will fight lazy-loads and N+1s during render.GeneratePdfJob writing to a private disk under a UUID filename, with a small pdfs table tracking owner, template, path, and expiry; return Storage::temporaryUrl() or a signed route.Maintenance. We are the maintenance plan. Zero dependents and 23 stars means no community backstop, no triage queue, and no one else finding the bugs first. The template layer is ours regardless — the package around it is plumbing we could replace in a day. The realistic ongoing cost is: pinning discipline on every composer update, a Chrome/Puppeteer CVE review cadence folded into existing dependency hygiene, and accepting that a Nova major upgrade will likely require forking or replacing this. Write a one-paragraph ADR documenting the fork-and-replace plan while the code is still small; it saves a scramble later and costs nothing now.
Support. Support surface splits cleanly. Template and layout issues are ours and will be the bulk of the volume — legal wants a footer change, ops wants a different page orientation. Rendering failures are the harder class and follow a deterministic debug ladder worth documenting for whoever is on call: (1) render the Blade view as plain HTML in a browser — does the markup look right? (2) run Browsershot standalone on that HTML outside Laravel — does Chromium launch and emit bytes? (3) check nodeBinary and chromePath against the container's actual paths; (4) check the worker's memory limit, since Chromium OOM kills surface as blank output or a silent exit rather than a clean exception; (5) check authorization, because a policy denial usually renders as "nothing happened," which reads like a render bug and wastes an hour. That ladder should live in the runbook, not in someone's head.
Scaling. The synchronous single-record design is the hard ceiling. A Chromium launch inside a Nova request will eventually meet an impatient user, a slow CDN font, or PHP's max_execution_time. The threshold is roughly 1–2 seconds; past that, queue it. Beyond queuing, the pattern does not extend to batch billing or nightly statement runs without meaningful rework — that is a different system with different retry, retention, and auditability requirements. If the roadmap contains batch document generation, this package is a spike, not a foundation, and should be labeled as such before it becomes load-bearing.
Failure modes. Enumerated because each one looks like something else:
waitUntil firing before assets load; non-deterministic, so it will pass in staging.handleBrowsershotOptions path is the least-tested surface in the package; page size, margins, and timeouts should be verified by measurement, not by config inspection.Ramp-up. Low for anyone comfortable with Laravel and Blade — the whole pattern is readable in an afternoon, and a competent engineer can go from zero to a working single-record PDF in one to three days. The non-obvious ramp-up cost is environmental, not code: Docker/Chromium configuration, --no-sandbox implications, font installation, and memory tuning. Budget that as infrastructure time, not feature time. And it needs to be said plainly in planning: adopting this is not "adding a Composer package," it is adopting a Node runtime, npm, and a patched Chrome binary as a side effect of an export button. If we already run headless Chrome elsewhere, that line item collapses to near zero and this becomes genuinely cheap. If we do not, the "free MIT package" is a new sidecar to operate, patch, and secure — and the honest PM recommendation is to fund it as such, or to harvest the ~150-line pattern into code we own and skip the dependency entirely.
How can I help you explore Laravel packages today?