Deprecating useGlobalAudioPlayer & Migration Steps

[E-Kuerschner]

TL;DR useGlobalAudioPlayer will be deprecated in the next minor release of v3 and removed completely in v4. Please refer to the brief migration steps at the end of this post.

As I prepare to release v4 of react-use-audio-player, I have made the difficult decision to deprecate useGlobalAudioPlayer. The ability to easily control a single, global audio source was the original use-case I had in mind when setting out to create this package years ago. To not leave you all high and dry (myself included), the next release react-use-audio-player will mark this hook as deprecated and provide a new, alternate solution.

Why are you doing this?

1. First and foremost, useGlobalAudioPlayer takes advantage of module-level state to share a single instance of an AudioPlayer across your application. Module-scoped variables are rarely advisable in NPM packages due to issues that arise in large applications with many transitive dependencies. Long story short, if you application somehow ended up with two versions of react-use-audio-player installed, the global hook would not be guaranteed to work correctly.
2. Sharing state is a built-in feature of React (i.e. context) and embracing its native functionality to provide nearly identical behavior reduces complexity by a high degree.
3. Being a solo maintainer is difficult. Maintaining a single hook that is focused on the core functionality will allow me to deliver features quicker.

The alternate solution

In the next minor release of v3, the package will begin exporting a React component: AudioPlayerProvider and a new hook: useAudioPlayerContext. To share audio between a set of components, first wrap those components in a single AudioPlayerProvider, then call useAudioPlayerContext to obtain the shared AudioPlayer instance.

As an added bonus, this context-based approach allows for many shared audio resources within your application whereas the deprecated useGlobalAudioPlayer hook limited you to one single audio resource.

Migration steps

To see a real-world example of migrating from useGlobalAudioPlayer to useAudioPlayerContext, take a look at the changes to the demo app in this PR.

1. Replace calls to useGlobalAudioPlayer with useAudioPlayerContext
2. Render all children invoking useAudioPlayerContext with a single <AudioPlayerProvider> element. The hook will throw an error if no provider has been rendered as an ancestor.

As always, thank you everyone who has used this package and submitted bugs and feature requests!