Jigsaw Laravel Package

Technical Evaluation

Architecture fit. Jigsaw is a build-time compiler, not a runtime package. It is installed as a standalone Composer project (composer create-project tightenco/jigsaw) and emits a directory of static HTML/CSS/JS from Blade templates and Markdown. It does not extend the host application's HTTP kernel, Eloquent models, queues, auth, or service container at runtime. The fit is therefore organizational rather than architectural: the team reuses Blade syntax, Laravel-style config, and PHP/Composer tooling, but nothing is shared at runtime. Layouts and components can be copy-pasted between the app and the site, not imported — unless we explicitly extract a shared Blade component package, which is extra scope. Treat Jigsaw as a sibling repository that happens to speak the same template language, not as a module of the Laravel application.

Integration feasibility. High. A working prototype is a day's work: scaffold, point CI at ./vendor/bin/jigsaw build production, publish the artifact to S3/CloudFront, Netlify, or GitHub Pages. jigsaw serve gives local preview. The friction is not technical setup — it is the constraints that come with a static output: no server-side forms, no authenticated content, no search without a third-party index (Algolia, Pagefind), no personalization, and no CMS unless we bolt one on. Content lives in Git, which means every copy change is a pull request. For a docs site or campaign landing page that is a feature; for a marketing team that expects a WYSIWYG editor it is a blocker we must plan around.

Technical risk. Blast radius is deliberately small — nothing here can take down the application. The real risks are:

• Content velocity. Editorial throughput becomes an engineering-adjacent bottleneck unless we pair Jigsaw with a Git-based CMS or accept a PR-review SLA.
• Dependency drift. Jigsaw pins its own illuminate/* versions and its own Node toolchain (Laravel Mix or Vite depending on release). That is a second PHP dependency graph to patch, independent of the app's Laravel version, and upgrades will not always land in lockstep.
• Strategic momentum. The low opportunity score (10.42) reads correctly: this is solved, table-stakes tooling with no differentiation. It is safe, but it is not a bet that compounds — and in a market that has drifted toward Astro and Next for static output, PHP-side SSG mindshare is flat.
• Single-owner knowledge. Typically one or two developers understand the config-as-PHP conventions (config.php, collections, front matter). That is a bus-factor risk, not a technology risk.

Key questions.

1. Which site is this for — documentation, campaign landing pages, or the main marketing site? Only the first two are good candidates for a first pass.
2. Who owns content day-to-day, and will they accept Markdown-in-Git plus PR review?
3. Do we need search, i18n, gated content, or forms? Each is an external service or a scope increase.
4. What is the realistic page count and acceptable build time at that count?
5. Does the org's design system and tooling standard point at PHP/Blade or at a JS framework? If the latter, Jigsaw is the wrong answer regardless of quality.
6. Who is on call when the deploy pipeline fails at 5pm on a Friday?

Integration Approach

Stack fit. Requires PHP 8.x, Composer, and Node for the asset pipeline. It slots cleanly into a Laravel shop's CI, coding standards, and Tailwind setup, and Blade familiarity removes the template learning curve entirely. It does not fit if the design system is React/Vue componentized and maintained by a frontend team — in that case Astro or Next is the honest recommendation, and pushing Jigsaw would create two component ecosystems.

Migration path. Two realistic origins:

• From Laravel-rendered marketing routes: build the static site alongside, map the URL structure one-to-one, and cut over per-path at the CDN/edge (or reverse proxy) so the application keeps ownership of anything dynamic. Strangler pattern, reversible per route.
• From WordPress or a legacy CMS: export content to Markdown, preserve permalinks exactly, and ship a 301 map as part of the cutover. Content migration, not code, is the long pole here — budget accordingly.

Compatibility. Verify three things before committing: (a) Jigsaw's pinned illuminate/* versions against the PHP version in our base images; (b) Node version required by Mix/Vite, since this is the most common breakage on CI image upgrades; (c) whether any custom Blade directives we rely on in the app are portable or need reimplementation. Deployment target is unconstrained — any static host or object store plus CDN works.

Sequencing. Do not start with the primary marketing site.

1. Pick one bounded, low-traffic surface — internal docs or a single campaign page.
2. Spike the full path: scaffold → CI build → deploy → custom domain. Prove the pipeline before proving the templating.
3. Port ~10 real pages and measure build time and authoring time honestly.
4. Define the editorial workflow (branching, preview deploys, review SLA) with the content owners in the room.
5. Add search and analytics as separate, deferrable workstreams.
6. Only then expand scope, and only if steps 3–4 produced numbers we like.

Operational Impact

Maintenance. Near-zero runtime maintenance — no servers, no PHP-FPM, no database, no security patching of a live application. What remains is two dependency tracks to keep current (Composer and npm) and a rebuild on every content change. Pin versions, wire Renovate or Dependabot, and assign a named owner. Note the favorable supply-chain position: dependents: 0 means this is never pulled in transitively, so there is no hidden dependency surface in production artifacts.

Support. No vendor SLA. Support is the Tighten docs, the issue tracker, and whoever on the team has done it before. The real support cost is editorial, not operational: content authors will need a written workflow and someone contractually obligated to review their PRs within a day. Without that, the site becomes the thing nobody can update.

Scaling. Request scaling is effectively free — a CDN absorbs any traffic pattern we are likely to see. The ceiling is build-time scaling: every content change triggers a full rebuild of every page, with no incremental build. That is comfortable in the hundreds of pages and starts to hurt in the low thousands, especially with image processing in the pipeline. Search, personalization, and A/B testing all require external services and should be treated as separate line items in any scaling plan.

Failure modes.

• Build failure on a content PR blocks publishing entirely — no partial deploy, no hotfix path outside Git.
• Permalink or front-matter changes silently break inbound links; needs a link checker in CI.
• Node major upgrade breaks the asset pipeline weeks before anyone notices.
• Blade compile errors surface only at build time — acceptable, but means CI is the only gate.
• build_local versus build_production config divergence produces staging/production drift.
• Stale content when a scheduled deploy is skipped; add a cron rebuild for anything date-sensitive.

Ramp-up. A Laravel developer is productive in one to two days; a content author needs about half a day plus a template. The genuine ramp cost is CI/CD and editorial process definition, which is one to two weeks of a TPM-plus-engineer pairing and is where most of the value and most of the risk sits. Budget for that explicitly rather than treating the tool as the whole project.