Building an Astro site with SPA-like page transitions & component framework

Swup & swup/astro come with most fixes for the typical problems but if you're using something else I'll resume the fixes here as I just went through this rabbit hole.

Steps

1. Pick a pjax routing library

Barba, swup, highway, taxi, etc

2. Update the `<head>`

If your pjax lib doesn't do it, you'll need to update the <head> after every route to import correct styles & scripts.

See how swup-head does it here.

3. Hydrate astro-islands

Make sure your component framework (react, vue, svelte, etc) hydrates properly on page navigation. Components from other pages than the first route won't hydrate properly with pjax. We can easily fix this - Astro appends the hydration script before any astro-island so you can do something like this after the pjax lib has swapped html:

function afterRoute() {
  // This will select all scripts that are followed by an astro-island
  const scripts = document.querySelectorAll('.wrapper script:has(+ astro-island)')
  scripts.forEach(runScript)
}

function runScript(script) {
  const element = document.createElement('script');
  for (const { name, value } of script.attributes) {
    element.setAttribute(name, value);
  }
  element.textContent = script.textContent;
  script.replaceWith(element);
  return element;
}

You can see how swup-scripts does it here.

4. Cleanup astro-islands

After navigating, you need to explicitely tell each island to unmount/"de-hydrate" so that you have no memory leaks or bugs. Astro islands are listening to specific events to cleanup themselves, so we just have to trigger these on navigation:

  // generic event names, refer to your pjax lib lifecycle docs
  const dispatch = (name) => document.dispatchEvent(new Event(name))
  router.on('beforeReplace', () => dispatch('astro:before-swap'))
  router.on('afterReplace', () => dispatch('astro:after-swap'))
  router.on('beforeAnimateIn', () => dispatch('astro:page-load'))

See how swup/astro does it here.

5. Extras

Smooth scroll

if you're using a global-level scrolling lib like lenis, you can create a single instance and reset it after the routing is done, i.e.:

if ('scrollRestoration' in history) {
  history.scrollRestoration = 'manual'
}
router.on('beforeAnimateIn', () => {
  lenis.scrollTo(0, { immediate: true, force: true })
  lenis.resize() // take new DOM height into account
})

Accessibility

Using front-end routing can be disorienting for users navigating with accessibility feature. To mitigate this you can add a live region that updates with the name of the newly navigated page, and mark the site as aria-busy during transitions. You can see how swup-a11y does it here.

Prefetching

Astro comes with its own prefetch system but I'm not sure it's compatible with a pjax lib - you might have to roll your own. Usually most pjax lib are built for this.

TBD

Will update when I run into other issues with a bigger project.

Hope this is helpful :)

ayamflow/astro-spa-transitions-framework.md