Sidecar Browsershot Laravel Package

Product Decisions This Supports

• Feature go/no-go on document generation. Invoice PDFs, statements, certificates, shipping labels, report exports, and OG/social images all become a one-package decision rather than a "we need to hire an ops person for Chrome" decision. The BrowsershotLambda::html(...) / ::url(...) API means a PDF feature can be scoped as a normal Laravel ticket.
• Build vs. buy on rendering infrastructure. The realistic alternative is standing up a dedicated Chrome/Puppeteer worker service, a container sidecar, or a paid third-party PDF API. This package is the "buy, but cheaply and in-house" middle option: MIT licensed, stays inside your AWS account, no per-document vendor fee. That's the comparison slide to bring to a build-vs-buy review.
• Architecture: offload heavy compute from the request path. Booting headless Chrome is a memory/CPU spike that competes with your web traffic. Moving it to Lambda is a product-level reliability decision (fewer 502s and OOM kills under load) as much as an engineering one.
• Container image and deploy-pipeline decisions. No Node, no Puppeteer, no Chrome in the app image means smaller images, faster CI, quicker rollbacks, and a materially smaller CVE-patching surface. This is the argument that usually wins with platform/security teams.
• Cost modelling. Lambda is pay-per-invocation; a dedicated Chrome worker is pay-per-hour-forever. For bursty or low-volume workloads (month-end invoicing, weekly reports) this is a clear cost win. SIDECAR_BROWSERSHOT_WARMING_INSTANCES is the explicit dial between latency and spend — treat it as a product tuning parameter, not a config detail.
• Scaling and launch decisions. Lambda absorbs concurrency spikes without you provisioning capacity, which de-risks a launch or a marketing push that triggers a burst of exports.
• Enterprise/brand requirements. Custom font registration via resources/sidecar-browsershot/fonts is the checkbox for brand-accurate documents and correct emoji rendering — the kind of thing that otherwise becomes a late-stage QA blocker on a customer-facing PDF.
• Data-handling decisions. readHtmlFromS3() and saveToS3() are not just size workarounds; they're the answer to "how do we generate a 200-page report" and "how do we avoid shipping large binaries back through the app server." They also shape your retention/storage story.
• Roadmap sequencing. Because it's a drop-in subclass of Spatie's Browsershot, you can ship PDF features now and swap the execution backend later without rewriting product code. That lowers the cost of choosing wrong.

When to Consider This Package

Adopt when most of these are true:

• You're a Laravel app already running on AWS, and Sidecar is acceptable (or already present).
• You already use spatie/browsershot, or would choose it — this package is strictly an execution-backend swap for that library, not a replacement.
• Document/screenshot volume is low-to-moderate or spiky rather than sustained high throughput.
• Your latency budget for a PDF is roughly a second or more — a user clicking "Download invoice" and waiting is fine; a synchronous call inside a page render is not.
• Nobody on the team wants to own headless Chrome in production, and there's no existing Chromium worker fleet to justify reusing.
• Container bloat, image build times, or OS-level patch load are active pain points.
• You need branded fonts and reliable emoji/CJK rendering in generated documents.

Look elsewhere when any of these are true:

• Not on AWS, or constrained to on-prem/air-gapped or a regulated environment where rendering customer HTML outside your VPC is a non-starter (EU data-residency reviews will ask).
• Steady high volume. At sustained throughput, per-invocation pricing and Lambda concurrency limits start losing to a long-lived worker container. Run the numbers before committing.
• Hard sub-second SLA, or an interactive UX where a cold start is visible. Warming instances mitigate this but reintroduce fixed hourly cost — at which point you're paying for a worker anyway.
• Payload sizes above Lambda request/response limits and no appetite for S3 round-trips (or no S3 write permissions for the Sidecar execution role).
• ARM/Graviton is a platform standard. The package only supports x86_64; that's a real constraint if your org has standardized on Graviton for cost reasons.
• Deep Puppeteer control is required — unusual Chrome flags, request interception, proxying, complex auth flows. Verify parity against your needs before betting a feature on it; the API mirrors Browsershot, but verify rather than assume.
• Adoption risk tolerance is low. 236 stars, zero dependents on Packagist, and effectively a single maintainer. It is well-tested (integration tests against real Lambda), has a changelog and releases through v2.3.x, and is a thin wrapper — but the bus factor is 1. Have a fallback: the abstraction is thin enough that reverting to self-hosted Browsershot is a config change plus infrastructure, which is exactly why the lock-in is low.
• You can't absorb a second deploy step. spatie/browsershot upgrades require redeploying the Lambda. If your release process can't carry that, it will drift out of sync and break in a confusing way.

How to Pitch It (Stakeholders)

For executives: We can ship PDF and screenshot features — invoices, reports, certificates, social images — without adding a service to operate or a per-document vendor bill. The heavy lifting runs on AWS Lambda inside our own account, billed per use, so cost tracks usage instead of headcount. It's MIT licensed, it's a thin wrapper over libraries we'd use anyway, and the exit cost is low: our product code stays on the standard Spatie Browsershot API, so switching back is an infrastructure change, not a rewrite. The main trade-off is a dependency on AWS Lambda and modest cold-start latency, which we can tune at a known cost.

For engineering: Install spatie/browsershot and hammerstone/sidecar, require this package, register BrowsershotFunction::class in sidecar.php, run php artisan sidecar:deploy --activate. Then replace Browsershot with BrowsershotLambda — existing chains, windowSize(), fit(), and save() keep working. You gain: no Node/Puppeteer/Chrome on app servers, lower memory and CPU on the web tier, saveToS3() and readHtmlFromS3() for large documents, and custom font bundling baked into the Lambda deploy. You take on: an x86_64-only Lambda function, a redeploy whenever spatie/browsershot is upgraded, optional spatie/image for image manipulation (note that fit() + saveToS3() downloads, manipulates, and re-uploads), and S3 write permissions on the Sidecar execution role. Add warming instances via SIDECAR_BROWSERSHOT_WARMING_INSTANCES if latency matters.

Diligence note to carry into the decision: single-maintainer project, small community, but active releases and a real integration test suite against AWS. Treat it as a low-risk, low-exit-cost dependency — not a platform bet.