Ux Swup Laravel Package

Product Decisions This Supports

• Perceived-performance roadmap item. Delivers SPA-like navigation (no full document reload, preserved scroll, animated transitions, prefetching) on an existing server-rendered app — a days-to-weeks alternative to an Inertia/React/Vue rewrite.
• Build vs buy. Adopt a thin integration layer over swup.js instead of hand-rolling history management, prefetch, and DOM-swap logic. MIT license and small surface area keep exit cost low: the thing you actually depend on is swup.js, not this wrapper.
• Use cases to prioritize it for: marketing/content sites, admin and back-office CRUD, docs portals, catalog/browse flows — any multi-page app where the pain is navigation latency, not client-side state complexity.
• Cheap experiment before a big bet. When stakeholders say "the app feels slow between pages," this is a scoped, reversible pilot with measurable outcomes (navigation timing, bounce on internal links, task completion) that informs a later frontend-architecture decision.
• Scoping signal against a framework migration. If the pilot satisfies users, it defers or eliminates an SPA rewrite on the roadmap; if it doesn't, you've spent a sprint, not a quarter, to learn that.
• Important framing correction: this is a Symfony UX package, not a Laravel one. On a Laravel codebase it is not a candidate at all — the comparable decisions are Livewire, Inertia, Turbo, or dropping swup.js into Blade directly.

When to Consider This Package

Consider it when:

• The stack is Symfony + Twig (AssetMapper or Encore) and Stimulus controllers are already the JS convention — the integration assumes this environment.
• The product will stay server-rendered; you want transitions and partial replacement, not client-owned application state.
• Your JS is lifecycle-clean: controllers implement connect/disconnect, initializers are idempotent, and nothing relies on a single DOMContentLoaded. Swup re-executes scripts per navigation.
• You've confirmed current maintenance status and Symfony-version compatibility. Low stars plus a thin wrapper means the real diligence is on swup.js itself.
• A 1–2 day spike across 3–5 representative pages can validate analytics, forms, third-party scripts, and focus management before committing.

Look elsewhere when:

• Laravel: use Livewire, Inertia, or Turbo — or use swup.js directly. This package adds nothing there.
• The UI genuinely needs client-side state (offline, optimistic updates, complex dashboards): use a real SPA framework or an Inertia/Livewire-style architecture.
• Pages depend on legacy jQuery plugins, ad scripts, or third-party widgets that don't survive DOM swaps — the integration cost becomes a recurring bug budget you own.
• You need vendor SLAs or guaranteed long-term support; a 33-star wrapper is a convenience, not a platform commitment.
• The team has no JS ownership. The failure mode here is subtle and user-visible (broken back button, duplicated analytics hits, lost focus) that PHP-focused developers may not catch in review.

Exit plan to state up front: keep swup.js, drop the wrapper. That's a contained change, not a migration.

How to Pitch It (Stakeholders)

For executives. "We can make the product feel like a single-page app without rebuilding it. This is a small, MIT-licensed integration that swaps page content instead of reloading the whole document — faster perceived navigation, preserved scroll and form state, no framework migration, no new infrastructure or hosting cost. Investment is a few days of engineering plus a short hardening pass. Risk is contained: we can remove it and fall back to standard page loads at any time."

For engineering. "It's thin Symfony UX glue over swup.js — Twig and Stimulus conventions, no lock-in, and the real dependency is swup.js. The work isn't installation, it's the audit: JS lifecycle correctness (connect/disconnect, idempotent initializers), analytics pageview tracking on soft navigations, form submission and redirect edge cases, and accessibility — focus management and live-region announcements on route change. Also flagging clearly: this is not a Laravel package. If the codebase is Laravel, the equivalents are Livewire, Inertia, or Turbo, or plain swup.js in Blade."

Recommendation. Pilot on one section behind a feature flag, instrument navigation timing and client error rates, and decide within 2–4 weeks. Treat the wrapper as disposable and swup.js as the asset.