Repository navigation
docs(site): add the vidstack migration guide - #3021
Conversation
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for vjs-registry canceled.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@videojs/cdn
@videojs/cli
@videojs/core
@videojs/element
@videojs/html
@videojs/media
@videojs/react
@videojs/spf
@videojs/store
@videojs/utils
@videojs/cloudflare-video
@videojs/dash-video
@videojs/hlsjs-video
@videojs/mux-audio
@videojs/mux-video
@videojs/native-hls-video
@videojs/shaka-video
@videojs/spotify-audio
@videojs/tiktok-video
@videojs/twitch-video
@videojs/vimeo-video
@videojs/wistia-video
@videojs/youtube-video
@videojs/google-cast
@videojs/mux-data
commit: |
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (18)
Players (5)
Skins (29)
UI Components (62)
⚛️ @videojs/react — no changesPresets (7)
Media (22)
Extensions (2)
Players (5)
Skins (18)
UI Components (39)
🧩 @videojs/core — no changesEntries (76)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (13)
📦 @videojs/cdn — no changes📦 @videojs/cloudflare-video — no changes📦 @videojs/dash-video — no changes📦 @videojs/google-cast — no changes📦 @videojs/hlsjs-video — no changes📦 @videojs/media — no changesEntries (3)
📦 @videojs/mux — no changes📦 @videojs/mux-audio — no changesEntries (2)
📦 @videojs/mux-data — no changes📦 @videojs/mux-video — no changesEntries (2)
📦 @videojs/native-hls-video — no changes📦 @videojs/shaka-video — no changes📦 @videojs/spf — no changesEntries (7)
📦 @videojs/spotify-audio — no changes📦 @videojs/tiktok-video — no changes📦 @videojs/twitch-video — no changes📦 @videojs/other — no changesEntries (3)
📦 @videojs/vimeo-video — no changes📦 @videojs/wistia-video — no changesEntries (2)
📦 @videojs/youtube-video — no changesℹ️ How to interpretEach entry is independently bundled, minified, and brotli-compressed. Initial size includes its static import graph; lazy dynamic chunks are reported separately. Entries are not additive because their dependency graphs overlap. Preset rows represent realistic combined bundles. Changes of 300 B or less across initial, lazy, and total size are collapsed, not discarded. Run |
c30adc1 to
ac231da
Compare
9348569 to
90eafc9
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 90eafc9. Configure here.
Maps Vidstack Player 1.x onto Video.js 10 for React and HTML: the player, providers, layouts, media store, events, styling, and features, with a Known gaps list and the checks that don't throw errors. Opens with a quickstart prompt that installs the Video.js skill and points agents at the guide copy shipped in node_modules. Registers the guide in the sidebar, the installation migration notice, the roadmap, the beta blog update, and each framework's llms.txt header. Refs #1409
Covers when HTML elements destroy themselves after removal, how keep-alive opts an element out, that descendants don't inherit it, and that packaged skins don't pass it to their controls.
The guide's prompt was a plain code block. It now uses the shared MigrationAgentStart the other migration guides use, with a vidstack source, so all five guides give agents the same prompt in the same card.
Every Known gaps item now links its issue, and the section points to the Vidstack Parity epic (#3035) that groups them. Sections that mention a gap elsewhere in the guide link the same issues. Time slider video previews, JSON storyboards, and swipe to scrub join the list, since they were only mentioned in passing before.
useMedia returns the generic media type, so checking for an engine key left engine typed as unknown and the hls.js calls failed to typecheck. The guide now narrows with instanceof HlsJsAdapter, and the listener types its parameters.
The store API changed under the guide: toggles became play, pause, setMuted, and request/exit pairs; toggleRemotePlayback became promptRemotePlayback; pip and fullscreen state became isPictureInPicture and isFullscreen; loadSource is gone; and canPlay now turns on at the native canplay point. selectSubtitlesTrack takes null to turn subtitles off. The HTML store example reads values off the store, and the guide links the new player store reference.
A pass over every claim against current source and Vidstack 1.15.6: - seek() rejects before the player attaches, like the other actions, and React mount effects run before the attach; - Vidstack's Default Layout already seeked 10 seconds, 20 with Shift; - the live window is measured from the live edge start, not the seekable end; - locale packs load only inside the i18n provider; - media elements release their engine through adapter.destroy(), and tear down in a microtask, so moves must be synchronous; - engine rebuild rules differ between hls.js and dash.js or Shaka, and the HTML engine example subscribes once loading starts; - smaller fixes to slot counts, data-active, Tailwind 3 syntax, crossOrigin, event objects, track fallback, and skin hotkeys.
Listening only for loadstart misses an engine that already exists when the code runs, so the HTML example subscribes straight away as well.
The migration prompts run past 1,100 pixels, so the prompt card now caps them the way code frames cap long code: 512 pixels unless the content only slightly exceeds it, with the same Show more and Show less controls. Both use one CollapsibleCode component extracted from TabsPanel; the card fades into its own soot background and scrolls back to itself on collapse.
The shared prompt reads the online guide first and switches to the docs shipped with the package once it's installed.
decepulis
left a comment
There was a problem hiding this comment.
this seems really great. just one nonblocking nit comment, but nothing structural or deep! Cursor seemed to have a reasonable comment, too?
The URL recipe switches on resolveAdapterType instead of hand-written regular expressions, loads each media lazily in both frameworks, and covers DASH, which Vidstack played too. The YouTube and Vimeo media now accept Vidstack's youtube/ID and vimeo/ID shorthands, with YouTube shorthands on the privacy-enhanced host, so the guide says they carry over and drops them from the known gaps.
9e3b991 to
bf3db24
Compare
The engine examples import Hls and HlsJsAdapter from @videojs/hlsjs-video, which the framework packages don't re-export. The guide now says that's the package readers installed for the hls.js media, and that it exports both for low-level access.

Closes #1409
Refs #1443, videojs/video.js#9417
Summary
This is the last of the migration guides the beta post promised, for Vidstack Player 1.x users moving to React or HTML. It opens by saying Vidstack is in security-only maintenance. It then gives the same agent prompt as the other migration guides: install the Video.js skill, read this guide and its Known gaps, take stock of the existing player, and plan the install with
npx @videojs/cli agents init. The rest maps each Vidstack concept to where it lives in Video.js 10.Preview
For review
media-play-buttonanddata-pausedsurvive, but their APIs changed.resolveAdapterType(from feat(media): add resolveAdapterType and resolveMimeType #3024) and load each media lazily, covering YouTube, Vimeo, HLS, DASH, and files. The YouTube and Vimeo media accept Vidstack'syoutube/IDandvimeo/IDshorthands, so those carry over and aren't listed as gaps.@videojs/html. Proper framework guides can follow separately.Changes
<media-player>prop went;.engine, YouTube/Vimeo shorthands and privacy defaults, and loading;asChild→renderand the popup model;play()/pause(),setMuted(), the request/exit pairs,promptRemotePlayback(),isFullscreen,isPictureInPicture, andselectSubtitlesTrack(null). TheloadSourcetip and the oldcanPlaynote are gone, and the guide links the new player store reference (docs(site): add player store api overview page #3034).llms.txt), the installation "Coming from another player?" notice, the roadmap, and the beta post's update note. Each framework'sllms.txtheader gets a Vidstack pointer next to the Video.js 8 one.MigrationAgentStartfrom docs(site): improve migration accuracy and agent guidance #3074, which the other four migration guides use, with a newvidstacksource. Rebasing onto docs(site): improve migration accuracy and agent guidance #3074 dropped this PR's own card and prompt components.TabsPanelinto a sharedCollapsibleCodecomponent that both use, so code blocks are unchanged. The migration prompts run past 1,100 px, so they collapse; the shorter Build with AI prompt doesn't.keep-aliveis now documented, in a "Lifecycle" section on the player reference (HTML only). It covers when elements destroy themselves, howkeep-aliveopts out, and that children don't inherit it. It also notes that packaged skins don't pass it to the controls in their shadow root.Testing
pnpm build:sitebuilds both framework pages, the.mdtwins, and thellms.txtentries. A first build caught a badDocsLinkslug, which is fixed.pnpm -F site test integrations/tests/llms-markdown.test.tsandpnpm -F site test diataxispass.Every code sample and claim was checked against
packages/and Vidstack 1.15.6 source: exports, props, action and state names, defaults, embed privacy behavior, the 24-name tag overlap, and all slugs and anchors.After the rebase, a second sweep checked every claim in the guide and the player reference's Lifecycle section against current main and Vidstack 1.15.6, and corrected 31 of them. Every in-page anchor,
DocsLink, linked issue, and import path resolves, and the code blocks that import Video.js typecheck, apart from the presetusePlayerselector typing, which fails on main itself.Not verified in a browser:
keep-alive. This is inferred fromDestroyMixinand custom element disconnect semantics; a happy-dom probe couldn't render the skin. Bug: Keep-Alive Doesn't Reach Packaged Skin Controls video.js#9418 tracks it.🤖 Generated with Claude Code
Note
Low Risk
Changes are documentation, nav/LLM index text, and a tested UI refactor for prompt display; no runtime player or auth logic.
Overview
Adds a Migrate from Vidstack guide (
migrate-from-vidstack.mdx) for Vidstack Player 1.x users moving to Video.js 10 on React or HTML, framed as a rewrite with maintenance context, AI quickstart viaMigrationAgentStart, and broad mapping tables (player/layout/store, media, skins, styling, gaps).Discovery and cross-links: Registers the guide in the Migrate sidebar, installation “Coming from another player?” aside, v10 roadmap, and the beta post update; each framework
llms.txtheader now points at Vidstack (vidstackvs@vidstack/react) alongside the existing Video.js 8 note.UX for long agent prompts: Introduces shared
CollapsibleCode(512px cap with slack, Show more/less, scroll-into-view on collapse), used byAgentPromptand refactoredTabsPanel; adds component tests.Reference: Documents HTML-only Lifecycle on the player component (
keep-alive, auto-destroy timing,destroy()/adapter.destroy()).Reviewed by Cursor Bugbot for commit 17b42b1. Bugbot is set up for automated code reviews on this repo. Configure here.