Ssg Laravel Package

Technical Evaluation

Architecture fit. statamic/ssg is a build-time compiler, not a runtime dependency. It executes inside an existing Laravel + Statamic application, crawls internal links, and emits a static HTML tree to disk. That single characteristic is what makes it a TPM-relevant decision rather than a developer convenience: it relocates operational risk out of the public request path (uptime, latency, autoscaling, attack surface) and into the build path (CI duration, artifact correctness, deploy orchestration). The package touches exactly three surfaces the adopting team already owns: an Artisan entry point (php please ssg:generate), a config file (config/ssg.php) that declares crawl scope, includes, excludes, and asset handling, and Laravel's filesystem for output. There is no API contract, no schema migration, no user-facing behaviour change, and no new vendor to procure. Coupling is low; the surrounding pipeline is the actual program of work, and a TPM should scope and staff it as such rather than as a package installation.

Integration feasibility. Two estimates must never be conflated in a status report, because stakeholders will anchor on the smaller one. Adopting the package is hours-to-a-day of Laravel-fluent engineering: composer require, publish config, enumerate routes, generate once, diff the output. Changing the delivery model is days to weeks: CI triggers, artifact storage, CDN configuration, cache invalidation, preview environments, rollback, staleness alerting — and much of that effort is not engineering time against this repository at all but platform, infra, and editorial-process work. Publishing a single "it's just a package install" number is the most common way this rollout gets mis-scheduled. The favorable side: the delivery target is host-agnostic (S3/CloudFront, Cloudflare Pages, Netlify, plain nginx), so the CDN decision can be evaluated on cost and operations independently rather than bundled into this adoption.

Technical risk. Low on the release itself, moderate one layer out. 4.1.0 contains exactly two changes: PHPUnit metadata migrated to attributes (test infrastructure only, zero runtime effect) and Laravel 13 support. No public API, config-schema, or generated-output changes versus 4.0, so the upgrade is non-breaking and low-ceremony. The real risk is version-matrix alignment: the widened illuminate/* constraints must co-resolve with the installed Statamic core major, and Laravel 13-era constraints typically move the PHP floor — which reaches CI images, build containers, and any preview host still pinned to an older runtime. Two secondary risks belong on the register from day one:

• Silent under-generation. config/ssg.php is a hand-maintained route manifest with no compiler to catch omissions. A page missing from the manifest produces no build error; it simply isn't there. This is a permanent low-grade correctness risk.
• Staleness. A broken CI pipeline serves the last good artifact indefinitely with no user-visible failure. Both risks are mitigated by cheap controls — a post-build route-count assertion, a link checker, and build-failure alerting — but only if they are planned, not discovered.

One ecosystem caveat worth naming to leadership: modest star count and effectively zero listed dependents means limited peer validation and no large body of community troubleshooting to lean on. Expertise must be built internally, not borrowed.

Key questions to answer before committing a date.

• Which Statamic core majors does 4.1.0 declare, and does that intersect with what we run? Who verifies, by when?
• Does the widened Laravel constraint raise our PHP floor, and do CI, build, and preview environments all meet it?
• What is the content-freshness SLA — on publish, hourly, daily? This single answer determines whether full rebuilds suffice or incremental generation becomes a requirement.
• Which page archetypes resist static serving (auth-gated views, form handling, personalization, live search over private data)? Who audits this archetype by archetype, and by when?
• Who owns config/ssg.php as a reviewable artifact, and what process keeps it in sync with routing?
• What is the definition of "correct output" — route-count parity, link integrity, byte-diff against the prior build?
• What is the rollback path if a bad build ships, and how long does restore actually take when rehearsed?

Integration Approach

Stack fit. Prerequisites are narrow and mechanically checkable: Laravel, Statamic installed, Composer 2, PHP at the floor implied by the new constraints, and a writable output directory. The generating environment needs nothing exotic — a standard CI runner is the natural execution target. The delivery target is host-agnostic, which is good procurement news: this package does not constrain the CDN decision, so hosting can be competitively evaluated on cost and operations rather than inherited from this rollout. Where Statamic is already in place, this is a low-incremental-cost path to static delivery versus re-platforming to Astro, Next.js, or Hugo; where it is not in place, adopting Statamic purely to get static generation is a coupling bet that warrants a spike, not a default.

Migration path — identify the lane explicitly, because effort differs by an order of magnitude and stakeholders will assume the cheapest one.

• 4.0.x → 4.1.0: a routine composer update. No config migration, no republished assets, no signature changes. One ticket. Do not inflate it into a release milestone.
• 3.x → 4.1.0: the migration project is the 4.0.0 major; 4.1.0 is merely the landing pad. Plan the major as its own effort and let this release be its tail.
• Greenfield: install 4.1.0 directly; skip intermediate versions entirely.

Compatibility — verify, don't infer. The release note says "supports Laravel 13"; it does not say what that does to our lockfile. Make verification a gate with a named owner and a date: run composer why-not statamic/ssg 4.1.0 on a branch, review the resolved lockfile diff, and confirm Statamic core, Laravel, and PHP all satisfy constraints simultaneously. Keep two decision tracks rigorously separate in the roadmap: the addon supporting Laravel 13 is not a mandate for the application to upgrade to Laravel 13. Merging those tracks manufactures an accidental forced migration out of a maintenance release — a classic TPM-visible schedule risk.

Sequencing — gates with exit criteria, because this is where the schedule actually lives.

1. Time-boxed spike (2–3 days). Generate once locally, serve the output, and classify every page archetype as static-safe, statically-degradable, or blocking. Exit criterion: a written blocker list. This is the earliest point at which a launch estimate becomes trustworthy — do not publish a date before it.
2. Compatibility gate. Composer update on a branch, resolved-matrix confirmation, lockfile diff reviewed and signed off by a named owner.
3. Output-diff gate. Full generation compared against the pre-upgrade build. Expected result is byte-identical modulo timestamps; any diff is a signal to investigate, not to rationalize.
4. Pipeline build-out (the long pole). CI job, artifact storage, CDN upload, cache invalidation, preview environment, documented rollback. Track as its own workstream with its own owner and its own status line.
5. Preview validation. Trailing slashes, redirects, 404 behaviour, and asset URLs verified against the real CDN configuration — not a local static server, which will lie to you.
6. Production promotion with the previous artifact retained and a rehearsed restore path.
7. Post-launch. Staleness monitor, build-failure alerting, and a scheduled review of the route manifest.

Operational Impact

Maintenance. Steady-state cost is genuinely small and concentrates in two places: the hand-curated route manifest and the deploy pipeline. Neither is self-healing. Assign a named owner for config/ssg.php and require manifest changes to be reviewed alongside routing changes — this is the control that prevents silent under-generation, and it is a process fix, not an engineering one. Budget a recurring half-day per quarter to re-verify the Composer matrix and re-run a clean generation, since addon and core majors move on different cadences and the static pipeline will otherwise drift out of the application's upgrade lane without anyone noticing.

Support. There is no vendor SLA and the ecosystem is thin — small star count, effectively no listed dependents. Troubleshooting knowledge must be built internally and captured in a runbook: how to reproduce a failed build locally, how to inspect an artifact, how to roll back, who to page. Treat the release notes as the primary source of truth and read them per release rather than assuming semantic-versioning safety; 4.1.0 happens to be genuinely non-breaking, but the same cannot be assumed for 4.2. Budget for one engineer to hold this as a secondary responsibility with documented coverage, so the pipeline is not a single-person bus factor.

Scaling. Scaling characteristics improve markedly and this is the strongest part of the business case. With no PHP or database in the request path, traffic scaling collapses to CDN egress, which is a commodity with predictable unit economics — useful for spiky or bursty properties like launch pages, event microsites, and docs portals. The constraint moves to build scaling: regeneration cost grows with page count and asset volume, and full rebuilds become the wrong tool once publish frequency rises or the site grows past the point where a rebuild is comfortably within CI budget. Watch for that inflection and flag it early; incremental generation is a different piece of work, not a config flag. Also note the read-heavy/write-light fit set — docs portals, marketing and brochure sites, blogs, event microsites — and treat any drift toward personalization or sub-minute freshness as a signal to revisit the architecture decision, not to patch around it.

Failure modes. Four are worth pre-mortem treatment, each with a detection control:

• Silent under-generation. A page absent from the manifest yields no error. Control: post-build route-count assertion against an expected inventory.
• Staleness. A broken CI job silently serves yesterday's content indefinitely. Control: build-failure alerting plus a freshness monitor that asserts artifact age against the freshness SLA.
• Broken-but-deployed. Bad HTML, dead links, or wrong asset URLs reach production. Control: link checker and preview validation against real CDN config as a pre-promotion gate.
• Matrix breakage. A routine dependency bump fails to resolve or raises the PHP floor out from under a build container. Control: scheduled matrix re-verification and pinned runtime images.

Ramp-up. Two distinct audiences with different curves. Engineering ramps quickly — Laravel-fluent developers are productive in a day, and the package's surface is small enough to read in an afternoon. Editors and content owners need a light but non-optional briefing on the changed mental model: publish is no longer instant, because content change now flows through build → deploy. Setting that expectation before launch prevents the most common post-launch complaint and the most common source of shadow workarounds. The organization as a whole needs a single owner for the build pipeline and a documented "is this page static-safe?" checklist used during rollout and at every subsequent content-archetype addition. Front-load that checklist into the spike; it is cheap to write and expensive to retrofit.

Recommendation. Treat the package as low-risk and adopt-worthy wherever Statamic is already in place, and gate the go/no-go decision on a short pipeline spike rather than on package capability — the package is not the variable, the pipeline is. Publish the two estimates separately (adopt the package: hours; change the delivery model: weeks), assign a named owner to the route manifest and another to the pipeline, and revisit the decision if content freshness, personalization, or traffic patterns shift toward genuinely dynamic needs.