Browsershot Laravel Package

Product Decisions This Supports

• Feature viability for document generation. Any roadmap item that says "generate a PDF" (invoices, quotes, statements, receipts, packing slips, compliance reports, contracts, certificates, tax summaries) can be scoped as a few days of work rather than a quarter. Because it renders HTML/CSS/JS through a real Chrome engine, the team reuses existing Blade views and Tailwind/CSS instead of maintaining a parallel PDF templating language. That materially changes the cost estimate on a common class of request.
• Build vs. buy for rendering infrastructure. The core decision this package informs is not "can we make a PDF" but "do we own a headless browser fleet or rent one." Browsershot makes the buy-side comparison concrete: it is the DIY path (self-hosted Chrome, MIT-licensed, no per-render fee) competing against SaaS APIs such as DocRaptor, PDFShift, Api2Pdf, or a managed Browserless instance. The PM decision is a unit-economics and ops-ownership tradeoff, not a capability one — capability is essentially equal.
• Image/screenshot features. Social share card generation (OG images), product or listing thumbnails, dashboard "export as PNG" buttons, and email preview screenshots all become cheap to ship. These are usually small, high-visibility, low-risk wins that pad a release and demonstrate velocity.
• Preview-before-commit UX. Because the same renderer produces both an on-screen HTML preview and the final PDF, you can eliminate the classic "the PDF looks nothing like the preview" support ticket — a known driver of refunds, re-sends, and CSAT damage on invoice/statement features.
• Content capture and archival. bodyHtml() and triggeredRequests() enable after-JavaScript content extraction and asset auditing — useful for compliance archival, saved snapshots, scraping partners' public pages, and verifying what third-party calls a page makes. Treat this as a secondary use case and validate it against legal/ToS before committing.
• Roadmap sequencing. If document generation is on the roadmap, adopt early. The package is trivial to integrate but demands an infrastructure work item (Node, Puppeteer, Chrome, memory, timeouts, queue workers). Deciding early lets you budget that work; deciding late turns a "simple feature" into a release-blocking platform task.
• Risk register input. The maintainer has shipped security fixes for local-file-read bypasses via file: URLs, UNC paths, and protocol-relative URLs (v5.2.1). That is a signal that user-supplied URLs or HTML flowing into this package is an SSRF and data-exfiltration surface. The PM decision is to gate the feature: allow-listed origins or internally generated HTML only, never a raw end-user URL from an untrusted tenant.
• Not a decision driver: the package score's low opportunity sub-score (44.5) and the "0 dependents" figure mostly reflect data-collection artifacts and a crowded category, not product risk. Weigh the 5.2k stars, MIT license, published docs/changelog, and continuous release cadence far more heavily.

When to Consider This Package

Adopt when most of these hold:

• The application is Laravel/PHP and the team already ships Blade templates — the incremental template work is near zero.
• You already run Node.js somewhere in the stack, or a Docker/Forge image lets you add Puppeteer + Chrome with acceptable effort. On a container platform this is a one-line Dockerfile change; on shared hosting it is a non-starter.
• Fidelity matters: modern CSS (flexbox, grid, web fonts, custom properties), charts drawn client-side, or pages that need JavaScript to finish rendering. Simpler PHP PDF libraries (dompdf, mPDF) will visibly fail here and are a false economy.
• Volume is moderate — realistically dozens to low thousands of renders per day. This comfortably fits behind a queue worker or two.
• Data sensitivity or cost sensitivity argues against shipping customer documents to a third-party rendering API.
• You need programmatic control (waits, selectors, viewport, media type, cookies, request interception) that SaaS APIs expose only partially or behind higher tiers.

Look elsewhere when any of these hold:

• No Node on the host and no appetite to add it. This is the single biggest disqualifier. Managed options (Browserless, PDFShift, DocRaptor) remove the operational burden entirely; Spatie's own docs point to the unmaintained v2 Chrome-CLI path for Node-less environments, which you should not start a new feature on.
• Serverless-only architecture (e.g., Vercel/Netlify functions, small Lambda bundles). Chrome's size and memory footprint fight the platform limits. Use a hosted rendering API and call it over HTTP.
• High sustained volume. Per-render Chrome cold starts, RAM (hundreds of MB per instance), and zombie-process management become a real SRE cost. At scale, a shared browser pool or a managed service is usually cheaper than the engineering time.
• You need document-format rigor rather than web-page fidelity: PDF/A for long-term archiving, tagged/accessible PDFs for public-sector or WCAG obligations, reliable page-break typography across hundreds of variable-length pages, or AcroForm fillable fields. PrinceXML or DocRaptor are built for this; headless Chrome is not.
• You need a vendor SLA, indemnification, or 24/7 support. MIT open source gives you none of that.
• The PDF is a one-off, low-value artifact — a manual export someone pastes into an email. A client-side window.print() stylesheet may be entirely sufficient and cost zero infrastructure.
• Windows-only hosting or environments where you cannot control Chrome's binary path; the package's Node/NPM path handling has needed fixes for paths containing spaces, which is a hint that exotic setups produce avoidable friction.

Adoption gate before committing: define where the URL/HTML input originates. If it can ever be tenant-controlled, require a hardening task (origin allow-list, disable local file access, network egress restrictions) as part of the estimate, not as a follow-up.

How to Pitch It (Stakeholders)

For executives (one paragraph):

Document and image generation is a recurring, well-understood need — invoices, statements, reports, share cards. Browsershot is a small, mature, MIT-licensed Laravel package (5.2k GitHub stars, active releases, published documentation and changelog, maintained by Spatie) that lets our existing web pages be turned into pixel-accurate PDFs and images using the same templates we already build. That means document features cost days instead of weeks, have no per-render licensing fee, and keep customer data inside our own infrastructure rather than sending it to a third-party rendering vendor. The tradeoff we are accepting is operational: it requires a headless Chrome runtime on our servers, which is a one-time infrastructure task and a small ongoing maintenance line. We should adopt it for document generation now, and revisit a managed rendering service only if volume grows enough that Chrome's memory footprint makes self-hosting the more expensive option.

For engineering (the ask):

• This is a thin, Laravel-idiomatic wrapper around Puppeteer. The API surface we need is small: Browsershot::html($blade)->save('invoice.pdf'), plus waits, viewport, and media-type options. It does not impose an architecture — jobs can call it directly and it composes naturally with queues.
• Integration cost is real but bounded: Node + Puppeteer + Chrome in the image, a queue worker with adequate memory and a hard timeout, and cleanup of the generated files. Plan for one infrastructure ticket, not zero.
• Security is the item we must not skip. Recent releases patched local-file-read bypasses (file: URLs, UNC paths, protocol-relative URLs). Any input reaching this package must be internally generated HTML or an allow-listed origin — no raw user-supplied URLs. Add egress restrictions on the render worker so a compromised render cannot reach internal services.
• Escape hatch is good: when Browsershot's fluent API runs out, you drop to arbitrary Puppeteer script — we are not boxed in by the wrapper. This is also the main reason to prefer it over simpler PHP PDF libraries: those cannot render our CSS or execute our chart JavaScript, and we would regret the shortcut within one design refresh.
• One caveat to record in the ADR: the project requires Puppeteer 23+ as of v5, so our Node baseline must be pinned and tracked. Expect occasional dependency bumps; budget a small recurring maintenance allowance rather than assuming zero.

Recommendation: Adopt for PDF and image generation in the Laravel application. Approve the infrastructure and security-hardening tickets alongside the feature. Do not adopt for PDF/A, tagged-accessible PDFs, or fillable forms — evaluate PrinceXML or a managed service for those specific requirements. Re-evaluate the build-vs-buy call if sustained render volume passes the point where Chrome worker time exceeds the cost of a metered rendering API.