feat!: use Video.js v10 media components

[luwes]

Summary

Moves ReactPlayer's media from the standalone *-video-element packages and @mux/mux-player-react onto the Video.js v10 React media components (@videojs/react/media/*). The public API stays the same apart from the breaking changes below: the same props, callbacks, static methods and lazy loading per player. Players are picked with v10's resolveAdapterType, so ReactPlayer recognizes the same sources as the media it renders. It also migrates the repo's tooling to pnpm and Vite+. (Includes #2050.)

Breaking change: this releases as a new major version (4.0.0). See Breaking changes below and the new v3 → v4 migration guide.

Requires @videojs/*@10.0.1, which fixes autoPlay on embeds and a React 18 dev warning (videojs/v10#3136), a crash when switching away from YouTube (videojs/v10#3153), and hands the adapter to mediaRef for streams (videojs/v10#3141).

How it works

Every v10 media component behaves like a <video> tag: the same attributes and on* callbacks, a ref that receives the rendered element, and a mediaRef that receives the playable media. That's the <video> itself for a file, or the playback adapter for a stream or an embed. ReactPlayer now exposes exactly the same ref and mediaRef, so the glue here is small:

• src/MediaPlayer.tsx: createMediaPlayer(Component, toMediaProps) maps src + config onto the v10 source prop. Everything else, ref and mediaRef included, passes through unchanged. v10 compares sources structurally, so nothing is memoized.
• src/sources.ts: the src/config → source mappings:
  • engineSource (the default): config is keyed by engine name exactly like v10's source.engine, so every player gets the same { src, engine: config } and reads only its own key. One prop still configures every player.
  • muxSource: ReactPlayer matches extension-less Mux URLs (stream.mux.com/<id>?…), which become { playbackId, playback }, with config.mux layered on top. Mux plays through hls.js, so it also reads config.hlsJs/config.nativeHls.
  • wistiaSource: src plus config.wistia as Wistia's own options.
• src/patterns.ts: resolves a URL to its player key once with resolveAdapterType (and resolveMimeType) from @videojs/react. Every built-in player key is a v10 adapter type, plus html, so each player's canPlay is canPlay('<key>'). Two rules stay on top: Mux URLs ending in .m3u8 still play with hls.js, and the HTML player keeps AUDIO_EXTENSIONS/VIDEO_EXTENSIONS as a fallback for extensions v10 doesn't recognize (m4v, m4b, weba, oga, spx, …).
• src/players.ts: each entry lazy-loads its @videojs/react/media/* component, so code splitting per player is unchanged.
• src/Player.tsx: drives playing, volume, playbackRate and pip through the media, composing its own ref with mediaRef via v10's useComposedRefs.
• src/HtmlPlayer.tsx: a native <video>/<audio> both renders and plays the media, so it is both ref and mediaRef.
• src/types.ts: Config is composed from the v10 *EngineConfig types, plus mux and wistia.

mediaRef.current is an HTMLMediaElement-like object for every player, so playing, volume, playbackRate, pip and mediaRef.current.currentTime = … work the same everywhere. ref.current is the DOM element: the <video>/<audio>, the embed's <iframe>, or <wistia-player>. mediaRef.current.engine is the engine for every adapter: hls.js, dash.js, or the embed's SDK.

Breaking changes

• React 17 is no longer supported. The peer range is now ^18 || ^19, because @videojs/react requires React 18 or later.

• config is keyed by v10 engine name and holds that engine's own options: config.hls is now config.hlsJs (hls.js config), config.dash is now config.dashJs (dash.js settings), plus nativeHls, youtube, vimeo, spotify, twitch and tiktok. config.mux takes MuxSource options (playback, poster, storyboard, drm); Mux reads config.hlsJs for its engine. The README table is updated.

  // before
  <ReactPlayer src={src} config={{ hls: { maxBufferLength: 60 }, youtube: { color: 'white' } }} />
  // after
  <ReactPlayer src={src} config={{ hlsJs: { maxBufferLength: 60 }, youtube: { color: 'white' } }} />

• Custom players receive the whole config rather than only their own key, and PlayerEntry no longer has a name field.

• ref points to the DOM element; the media API moves to the new mediaRef prop. For files both are the <video>/<audio> element. For HLS, DASH and Mux, ref is the <video> and mediaRef is the playback adapter that drives it. For embeds, ref is the <iframe> (<wistia-player> for Wistia) and mediaRef is the playback adapter, where ref used to be a media custom element.

  // before
  <ReactPlayer ref={playerRef} src={src} />
  playerRef.current.currentTime = 30;
  // after
  <ReactPlayer mediaRef={mediaRef} src={src} />
  mediaRef.current.currentTime = 30;

• Custom players must forward ref to the element they render and hand the media to the mediaRef prop, like the v10 media components.

• Engines moved from ref.current.api to mediaRef.current.engine, for every player except Wistia: hls.js for HLS and Mux, dash.js for DASH, and the embed's SDK for YouTube, Vimeo, Spotify, Twitch and TikTok.

• Mux plays with MuxVideo instead of Mux Player: no built-in UI (use controls, or a v10 skin or UI components), no automatic poster, and no built-in Mux Data. Mux Data and Google Cast now come from v10 extensions: wrap ReactPlayer in v10's VideoPlayer and add <MuxData />, <GoogleCast /> and <CastButton /> next to it (see New).

• Media Chrome, which v3's README suggested for custom controls, can no longer control embeds, because slot="media" now lands on the embed's <iframe>. File, HLS, DASH and Mux sources still render a <video>. v4 recommends Video.js v10 skins or UI components instead (see New), which work with every source.

• Some embed options changed shape to match the providers' own parameters: Spotify startAt → t and theme: 'dark' → theme: 0, TikTok booleans → 0 | 1, Twitch time number → '1h30m10s'. The unused config.html is removed.

• react-player/patterns no longer exports the URL regexes (HLS_EXTENSIONS, DASH_EXTENSIONS, MATCH_URL_MUX, MATCH_URL_YOUTUBE, MATCH_URL_VIMEO, MATCH_URL_WISTIA, MATCH_URL_SPOTIFY, MATCH_URL_TWITCH, MATCH_URL_TIKTOK), and canPlay is a function of the player key: canPlay.youtube(url) becomes canPlay('youtube')(url). Use resolveAdapterType from @videojs/react to classify URLs:

  import { resolveAdapterType } from '@videojs/react';
  
  resolveAdapterType('https://youtu.be/oUFJJNQGwhk'); // 'youtube'

New

• URL matching loses nothing that played in v3. v3's regexes also matched youtube.com/user/…, vimeo.com/channels/…, vimeo.com/showcase/… and Twitch's own player.twitch.tv/?video=v…&parent=… embed URLs, but the v3 player elements couldn't parse those either. The two that did play, music.youtube.com/watch?v=… and player.twitch.tv/?video=<id>, are tracked upstream in Bug: resolveAdapterType Rejects music.youtube.com and player.twitch.tv URLs That the Embeds Can Play videojs/v10#3139 and need that fix before release (see the checklist).

• Custom controls with Video.js v10 skins or UI components. Wrap ReactPlayer in v10's VideoPlayer and add a skin or individual controls; they drive files, streams and embeds alike. The README's Media Chrome example is replaced with these:

  <VideoPlayer>
    <VideoSkin style={{ aspectRatio: '16 / 9' }}>
      <ReactPlayer src={src} width="100%" height="100%" />
    </VideoSkin>
  </VideoPlayer>

• Mux Data and Google Cast via v10 extensions. ReactPlayer's media attaches to a surrounding v10 player, so v10's extensions follow it whatever the source:

  <VideoPlayer>
    <ReactPlayer src={src} controls />
    <MuxData />
    <GoogleCast />
    <CastButton />
  </VideoPlayer>

  The v10 media components did this already; HtmlPlayer now registers its native <video>/<audio> too (useMediaAttach, like v10's Video). The README and migration guide document it.

• Newly recognized sources: localized Spotify URLs (open.spotify.com/intl-de/track/...), spotify: URIs, youtube/<id> and vimeo/<id> shorthands, and .flac files.

Other changes

• MIGRATING.md has a v3 → v4 section covering every breaking change, plus how to add Mux Data and Google Cast, and the README links to it.
• ReactPlayer finds the active player with Array#find/#some, and VideoElementProps extends React's own VideoHTMLAttributes instead of redeclaring it.
• The demo targets es2020, because @wistia/wistia-player contains BigInt literals.
• Removed the unused cloudflare-video-element dependency.
• Tooling migrated to pnpm and Vite+ (a424322), replacing npm, the custom scripts/builder/scripts/tester esbuild wrappers, Biome, c8 and zora/sinon:
  • build: vp pack (unbundled ESM, es2019) with tsgo declarations
  • demo: a Vite app in examples/react that resolves react-player to src
  • test: vp test (Vitest); tests are named *.test.* and run on Node 22 without flags
  • lint/format: Oxlint and Oxfmt via vp check, with a vp staged pre-commit hook; the codebase is formatted with Oxfmt
  • typecheck: tsgo --noEmit
  • CI/CD: pnpm, Node from .node-version, plus a typecheck step

Testing

• pnpm lint, pnpm typecheck, pnpm test, pnpm build and pnpm build:demo pass, on each commit.
• New test/MediaPlayer.test.tsx (source mapping, prop/callback pass-through, ref as the element and mediaRef as the media via a fake adapter, playback props driven through the media) and test/sources.test.tsx (the mappings), plus tests that config never reaches a native <video>, that a native player hands the same element to ref and mediaRef, that ReactPlayer's media attaches to a surrounding v10 player, and that a v10 PlayButton plays it (both fail without the HtmlPlayer change), and that mediaRef is the same hls.js adapter as useMedia(), with engine, for a stream.
• Checked in headless Chrome against @videojs/*@10.0.1 and live sources:
  • Switching from YouTube to an MP4 and to Vimeo, and unmounting ReactPlayer on YouTube, no longer crash (Bug: Unmounting <YouTubeVideo> crashes React with removeChild because the IFrame API's destroy() removes the iframe videojs/v10#3153).
  • HLS, DASH and Mux: mediaRef is the adapter, engine is hls.js or dash.js, and playing plays and pauses through it. An extension-less Mux URL gets its playback ID and poster.
  • autoPlay muted starts YouTube and Vimeo.
  • An MP4 plays via playing.
  • No React warnings in the console.
• Checked end to end in jsdom with the real YouTubeVideo inside ReactPlayer's Player: the media is the YouTubeAdapter with target set to the <iframe>, volume/playbackRate are applied, config.youtube reaches the embed URL, and onReady/onStart/onPlay fire. (Checked before config was re-keyed and before the ref/mediaRef split, when that adapter was on ref.)
• Compared player selection before and after resolveAdapterType across ~50 URLs; the differences are the URLs described under New, each checked against the v3 player elements' own parsers. The canPlay(key) refactor picks the same player as the previous commit for every URL.
• Wistia, Spotify, Twitch and TikTok were only checked for switching away to an MP4, not for playback; see the checklist below.

Before merging

• fix(react): accept autoPlay on embeds and drop callback-ref cleanups that warn on React 18 videojs/v10#3136 released; bump @videojs/* to that version (10.0.1)
• Bug: resolveAdapterType Rejects music.youtube.com and player.twitch.tv URLs That the Embeds Can Play videojs/v10#3139 released (music.youtube.com and player.twitch.tv URLs), so URL matching has no regressions from v3. Still open; 10.0.1 still resolves both to null.
• Manual browser check of each player in the demo (pnpm start)
• Manual check of <MuxData /> and <GoogleCast /> around ReactPlayer in a browser
• Manual check of VideoSkin around ReactPlayer for a file, an HLS stream and an embed (sizing, controls, fullscreen)

[decepulis]

Huge. Excited for how this sets up react-player to take advantage of everything Video.js has to offer!