Why does my Stimulus-driven Plyr audio player become unresponsive after using Safari’s back button?

Below is a few troubleshooting ideas and code adjustments you can make so that your Plyr instance initializes properly even when the browser restores a cached page (as happens on Safari when using the back button).

---

Why It May Be Failing

Your controller’s connect() checks for an existing element (via .plyr__controls) and, if found, skips creating a new player instance. However, when navigating “back,” the DOM is restored from cache so that the controls element already exists, even though the internal event bindings or state of the Plyr instance may have been lost. This results in an unresponsive player.

---

Steps to Debug

1. Log More Information:
   Ensure you’re logging essential information (like the element’s state) to verify whether the audio element and its Plyr controls are indeed in a stale state after a back navigation.

2. Inspect the DOM:
   Use Safari’s developer tools to check if the DOM contains multiple instances or if the element’s event listeners are active when the page is restored.

3. Check for Turbo Caching (if applicable):
   If you’re using Turbo, remember that it caches the page so that only the connect() method is fired when navigating back. Ensure that any dynamic JavaScript state is cleaned up before caching.

---

How to Fix It

Option 1: Always Reinitialize via a Cleanup in disconnect()

If you’re using Stimulus with Turbo or similar caching, add a disconnect() lifecycle callback that destroys the Plyr instance. This ensures that when the page is cached, you’re not keeping stale state. For example:

JAVASCRIPTCopied
import { Controller } from "@hotwired/stimulus"
import Plyr from "plyr"

export default class extends Controller {
  static values = { url: String }

  connect() {
    console.log("Plyr controller connected")
    // Do not rely on existing DOM state – always create a new player instance.
    this.player = new Plyr('#player', {
      controls: [
        'play',
        'progress',
        'current-time',
        'duration',
        'mute',
        'volume',
        'restart'
      ]
    })

    this.player.on('ended', (event) => {
      const badge = document.getElementById('badge')
      badge.classList.remove("greyed-out")
      badge.classList.add("jelly-animation")
      this.postEvent()
    })
  }

  disconnect() {
    // Clean up to prevent stale instances on cached pages.
    if (this.player) {
      this.player.destroy()
      this.player = null
    }
  }

  async postEvent() {
    // ... your POST/event logic
  }
}

Option 2: Use Turbo’s before-cache Event

If you’re using Turbo, you can listen for the turbo:before-cache event to remove any DOM changes done by Plyr before the cache is stored. For example, in your controller you might add:

JAVASCRIPTCopied
import { Controller } from "@hotwired/stimulus"
import Plyr from "plyr"

export default class extends Controller {
  static values = { url: String }

  connect() {
    console.log("Plyr controller connected")
    this.player = new Plyr('#player', { /* options as before */ })
    this.setupBeforeCacheListener()
  }

  disconnect() {
    if (this.player) {
      this.player.destroy()
      this.player = null
    }
  }

  setupBeforeCacheListener() {
    document.addEventListener('turbo:before-cache', () => {
      if (this.player) {
        this.player.destroy()
        this.player = null
      }
    })
  }

  async postEvent() {
    // ... your POST/event logic
  }
}

This makes sure that when Turbo caches the page, you remove any leftover Plyr state so that a fresh instance is created on reconnect.

---

Summary

• The conditional checking for .plyr__controls might be preventing a new Plyr instance (and its event bindings) from being created on page restoration.
• Clean up or always reinitialize your player in Stimulus’ lifecycle callbacks (either via disconnect() or Turbo’s before-cache event) so that on navigating back the Plyr instance is fully functional.
• Add extra console logs and inspect the DOM to see what may be lingering after a back navigation.

Following these steps should help you debug the issue and ensure that your player works correctly even after using browser history navigation.