Astro View Transitions：ページ遷移時に状態や再生を維持する方法

Astro Frontend Performance HTML
結論

ページ遷移時の要素破棄を防ぐには、対象要素に transition:persist を記述します。

---
// Astro公式仕様：View Transitions と transition:persist の設定
import { ClientRouter } from 'astro:transitions';
import AudioPlayer from '../components/AudioPlayer.jsx';
---

<html lang="ja">
  <head>
    <!-- 1. クライアントサイドルーティングを有効化 -->
    <ClientRouter />
  </head>
  <body>
    <main>
      <slot />
    </main>

    <!-- 2. ページ遷移時も音声再生状態を途切れさせず永続化 -->
    <AudioPlayer client:load transition:persist="global-audio-player" />
  </body>
</html>

Astro公式仕様：View Transitions 永続化メカニズム

Astro公式ドキュメント（docs.astro.build/en/guides/view-transitions/）の規定通り、<ClientRouter />（旧 <ViewTransitions />）を適用したサイトでは、リンククリック時に標準のブラウザページ全読み込みではなく、クライアントサイドでHTMLがフェッチ・置換されます。

標準ではDOMが全入れ替えされますが、transition:persist を付与した要素は、新しいページのDOMツリー構築時にも破棄されず、同一インスタンスのまま引き継がれます。

実際に起こる障害：ページ遷移によるメディア再生のブツ切り事故

ポッドキャスト配信サイトや動画ポータルにおいて、サイト内回遊（/episodes → /about）を行った際、transition:persist が設定されていないと、ページ遷移の瞬間にDOM要素が削除されるため、再生中の音声・動画が突然ストップし、再生バーが初期位置へ巻き戻る障害 が発生します。

設定手順とオプション使い分け

  1. ルートレイアウト（Layout.astro）の <head> 内に import { ClientRouter } from 'astro:transitions' を配置する
  2. 保持したいプレイヤーやコンポーネントに transition:persist="固有ID" を記述する
  3. 状態は維持しつつ、新ページの props 値のみをコンポーネントへ反映させたい場合は transition:persist-props を併用する
<!-- 新ページの props 値のみを安全に同期更新する指定 -->
<HeaderCounter client:load transition:persist transition:persist-props />