Skip to content
This repository was archived by the owner on Oct 21, 2026. It is now read-only.

docs(site): add the vidstack migration guide - #3021

Merged
mihar-22 merged 17 commits into
mainfrom
t3code/vidstack-migration-guide
Oct 1, 2026
Merged

mihar-22 merged 17 commits into
mainfrom
t3code/vidstack-migration-guide

Conversation

@mihar-22

@mihar-22 mihar-22 commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

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

  • Maintenance window. The note at the top says we'll merge priority security patches into 1.x until January 2028.
  • Framing. It follows the Video.js 8 guide: plan a rewrite of your player setup rather than a find-and-replace. Names like media-play-button and data-paused survive, but their APIs changed.
  • Automatic source selection. The guide says a media component that picks its engine from the source is planned, says the API isn't settled, and links Feature: Provide a URL-Based Video Source Detection Facade video.js#9290. Until then, the React and HTML recipes switch on 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's youtube/ID and vimeo/ID shorthands, so those carry over and aren't listed as gaps.
  • Angular and Solid get a short section on using @videojs/html. Proper framework guides can follow separately.

Changes

  • The guide, with React and HTML variants throughout. It covers:
    • the three-piece model and a terminology table;
    • a first player built from the Default Layout;
    • where each <media-player> prop went;
    • providers → media components: HLS/DASH engine config, .engine, YouTube/Vimeo shorthands and privacy defaults, and loading;
    • layouts → skins: layout props, slots → skin source, customization levels;
    • styling: state attributes, theme variables by meaning, Tailwind, responsive, color scheme, icon renames;
    • a component map, including asChild → render and the popup model;
    • state, actions, and events;
    • captions, chapters, and thumbnails; hotkeys and gestures; fullscreen; live; casting; languages; preferences and autoplay;
    • a checklist of behavior changes that don't throw errors, and Known gaps with their tracking issues.
  • Parity links. Each Known gaps item links its issue under the new Vidstack Parity epic (#3035), except request events, which are out by design. Prose and table rows that name a single gap elsewhere in the guide link the same issues. The epic groups 21 new issues (#3036–#3056) and 15 existing ones, including Feature: Navigate to a Chapter From a List #1873 and Feature: Supply Chapters Programmatically #1268, which moved over from the closed Chapters epic Feature: Chapters #1441.
  • Store API. Rebased onto main after refactor(core)!: align player store API #3012 and refactor(media)!: tidy text track state #3057. The action and state tables use play()/pause(), setMuted(), the request/exit pairs, promptRemotePlayback(), isFullscreen, isPictureInPicture, and selectSubtitlesTrack(null). The loadSource tip and the old canPlay note are gone, and the guide links the new player store reference (docs(site): add player store api overview page #3034).
  • HTML-only warning. Vidstack and Video.js register 24 of the same custom element names, so HTML users have to remove Vidstack in the same change.
  • Registration. The guide is in the Migrate sidebar group (which also feeds llms.txt), the installation "Coming from another player?" notice, the roadmap, and the beta post's update note. Each framework's llms.txt header gets a Vidstack pointer next to the Video.js 8 one.
  • AI Quickstart card. The guide uses the shared MigrationAgentStart from docs(site): improve migration accuracy and agent guidance #3074, which the other four migration guides use, with a new vidstack source. Rebasing onto docs(site): improve migration accuracy and agent guidance #3074 dropped this PR's own card and prompt components.
  • Collapsible prompts. Long agent prompts now collapse like code blocks: the card caps them at 512 px, unless they only slightly exceed it, with the same Show more and Show less controls. The behavior moves out of TabsPanel into a shared CollapsibleCode component 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-alive is now documented, in a "Lifecycle" section on the player reference (HTML only). It covers when elements destroy themselves, how keep-alive opts 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:site builds both framework pages, the .md twins, and the llms.txt entries. A first build caught a bad DocsLink slug, which is fixed.

  • pnpm -F site test integrations/tests/llms-markdown.test.ts and pnpm -F site test diataxis pass.

  • 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 preset usePlayer selector typing, which fails on main itself.

Not verified in a browser:

🤖 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 via MigrationAgentStart, 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.txt header now points at Vidstack (vidstack vs @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 by AgentPrompt and refactored TabsPanel; 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.

@netlify

netlify Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for vjs10-site ready!

Name Link
🔨 Latest commit 17b42b1
🔍 Latest deploy log https://app.netlify.com/projects/vjs10-site/deploys/6abdcaabfa4743000714c6c4
😎 Deploy Preview https://deploy-preview-3021--vjs10-site.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify

netlify Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for vjs-registry canceled.

Name Link
🔨 Latest commit 17b42b1
🔍 Latest deploy log https://app.netlify.com/projects/vjs-registry/deploys/6abdcaab2e850e00086349b4

@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
v10-sandbox Ready Ready Preview Oct 1, 2026 2:52am UTC

Request Review

@pkg-pr-new

pkg-pr-new Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
@videojs/cdn

pnpm add https://pkg.pr.new/@videojs/cdn@3021

@videojs/cli

pnpm add https://pkg.pr.new/@videojs/cli@3021

@videojs/core

pnpm add https://pkg.pr.new/@videojs/core@3021

@videojs/element

pnpm add https://pkg.pr.new/@videojs/element@3021

@videojs/html

pnpm add https://pkg.pr.new/@videojs/html@3021

@videojs/media

pnpm add https://pkg.pr.new/@videojs/media@3021

@videojs/react

pnpm add https://pkg.pr.new/@videojs/react@3021

@videojs/spf

pnpm add https://pkg.pr.new/@videojs/spf@3021

@videojs/store

pnpm add https://pkg.pr.new/@videojs/store@3021

@videojs/utils

pnpm add https://pkg.pr.new/@videojs/utils@3021

@videojs/cloudflare-video

pnpm add https://pkg.pr.new/@videojs/cloudflare-video@3021

@videojs/dash-video

pnpm add https://pkg.pr.new/@videojs/dash-video@3021

@videojs/hlsjs-video

pnpm add https://pkg.pr.new/@videojs/hlsjs-video@3021

@videojs/mux-audio

pnpm add https://pkg.pr.new/@videojs/mux-audio@3021

@videojs/mux-video

pnpm add https://pkg.pr.new/@videojs/mux-video@3021

@videojs/native-hls-video

pnpm add https://pkg.pr.new/@videojs/native-hls-video@3021

@videojs/shaka-video

pnpm add https://pkg.pr.new/@videojs/shaka-video@3021

@videojs/spotify-audio

pnpm add https://pkg.pr.new/@videojs/spotify-audio@3021

@videojs/tiktok-video

pnpm add https://pkg.pr.new/@videojs/tiktok-video@3021

@videojs/twitch-video

pnpm add https://pkg.pr.new/@videojs/twitch-video@3021

@videojs/vimeo-video

pnpm add https://pkg.pr.new/@videojs/vimeo-video@3021

@videojs/wistia-video

pnpm add https://pkg.pr.new/@videojs/wistia-video@3021

@videojs/youtube-video

pnpm add https://pkg.pr.new/@videojs/youtube-video@3021

@videojs/google-cast

pnpm add https://pkg.pr.new/@videojs/google-cast@3021

@videojs/mux-data

pnpm add https://pkg.pr.new/@videojs/mux-data@3021

commit: 17b42b1

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size Report

🎨 @videojs/html — no changes
Presets (7)
Entry Initial Lazy
/video (default) 64.34 kB 56.03 kB
/video (default + hls) 66.08 kB 56.03 kB
/video (minimal) 64.88 kB 56.03 kB
/video (minimal + hls) 66.49 kB 56.03 kB
/audio (default) 48.22 kB 56.03 kB
/audio (minimal) 48.49 kB 56.03 kB
/background 11.86 kB 56.03 kB
Media (18)
Entry Initial
/media/mux-video 3.01 kB
/media/mux-audio 2.68 kB
/media/background-video 1.16 kB
/media/cloudflare-video 2.90 kB
/media/dash-video 2.63 kB
/media/hls-audio 23.47 kB
/media/hls-background-video 17.44 kB
/media/hls-video 33.65 kB
/media/hlsjs-video 2.63 kB
/media/mux-background-video 17.42 kB
/media/native-hls-video 7.68 kB
/media/shaka-video 2.63 kB
/media/spotify-audio 3.02 kB
/media/tiktok-video 3.12 kB
/media/twitch-video 2.93 kB
/media/vimeo-video 2.90 kB
/media/wistia-video 607 B
/media/youtube-video 2.90 kB
Players (5)
Entry Initial Lazy
/video/player 9.96 kB 56.03 kB
/audio/player 6.14 kB 56.03 kB
/background/player 4.46 kB 56.03 kB
/live-video/player 9.33 kB 56.03 kB
/live-audio/player 6.16 kB 56.03 kB
Skins (29)
Entry Type Initial Lazy
/video/minimal-skin.css css 8.29 kB —
/video/skin.css css 8.00 kB —
/video/minimal-skin js 63.24 kB 56.03 kB
/video/minimal-skin2 js 8.27 kB —
/video/skin js 62.80 kB 56.03 kB
/video/skin2 js 7.99 kB —
/audio/minimal-skin.css css 6.07 kB —
/audio/skin.css css 5.80 kB —
/audio/minimal-skin js 47.00 kB 56.03 kB
/audio/minimal-skin2 js 6.05 kB —
/audio/skin js 46.71 kB 56.03 kB
/audio/skin2 js 5.78 kB —
/background/skin.css css 141 B —
/background/skin js 10.11 kB 56.03 kB
/background/skin2 js 159 B —
/live-video/minimal-skin.css css 6.77 kB —
/live-video/skin.css css 6.69 kB —
/live-video/minimal-skin js 50.80 kB 56.03 kB
/live-video/minimal-skin2 js 6.77 kB —
/live-video/skin js 50.73 kB 56.03 kB
/live-video/skin2 js 6.67 kB —
/live-audio/minimal-skin.css css 4.77 kB —
/live-audio/skin.css css 4.67 kB —
/live-audio/minimal-skin js 36.17 kB 56.03 kB
/live-audio/minimal-skin2 js 4.77 kB —
/live-audio/skin js 36.14 kB 56.03 kB
/live-audio/skin2 js 4.66 kB —
/global.css css 239 B —
/shadow.css css 78 B —
UI Components (62)
Entry Initial Lazy
/ui/airplay-button 11.52 kB 56.03 kB
/ui/alert-dialog 8.98 kB 56.03 kB
/ui/audio-track-radio-group 11.61 kB 56.03 kB
/ui/buffering-indicator 8.85 kB 56.03 kB
/ui/captions-button 11.76 kB 56.03 kB
/ui/captions-radio-group 11.66 kB 56.03 kB
/ui/cast-button 11.51 kB 56.03 kB
/ui/container 9.72 kB 56.03 kB
/ui/controls 9.03 kB 56.03 kB
/ui/controls-backdrop 1.69 kB 56.03 kB
/ui/controls-content 1.67 kB 56.03 kB
/ui/dialog 8.92 kB 56.03 kB
/ui/dialog-backdrop 1.70 kB 56.03 kB
/ui/dialog-close 2.06 kB 56.03 kB
/ui/dialog-description 1.69 kB 56.03 kB
/ui/dialog-popup 1.90 kB 56.03 kB
/ui/dialog-title 1.70 kB 56.03 kB
/ui/error-dialog 12.62 kB 56.03 kB
/ui/fullscreen-button 11.50 kB 56.03 kB
/ui/gesture 9.95 kB 56.03 kB
/ui/hotkey 10.37 kB 56.03 kB
/ui/live-button 10.03 kB 56.03 kB
/ui/menu 19.19 kB 56.03 kB
/ui/menu-checkbox-item 1.97 kB 56.03 kB
/ui/menu-content 7.64 kB 56.03 kB
/ui/menu-group 2.09 kB 56.03 kB
/ui/menu-group-label 1.64 kB —
/ui/menu-item 2.29 kB 56.03 kB
/ui/menu-item-indicator 1.38 kB 56.03 kB
/ui/menu-radio-group 3.02 kB 56.03 kB
/ui/menu-radio-item 2.14 kB 56.03 kB
/ui/menu-separator 1.30 kB 56.03 kB
/ui/mute-button 11.52 kB 56.03 kB
/ui/pip-button 11.48 kB 56.03 kB
/ui/play-button 11.46 kB 56.03 kB
/ui/playback-rate-button 11.56 kB 56.03 kB
/ui/playback-rate-radio-group 11.62 kB 56.03 kB
/ui/popover 8.76 kB 56.03 kB
/ui/poster 9.16 kB 56.03 kB
/ui/quality-radio-group 12.13 kB 56.03 kB
/ui/seek-button 11.50 kB 56.03 kB
/ui/seek-indicator 12.94 kB 56.03 kB
/ui/seek-indicator-value 1.10 kB —
/ui/slider 11.89 kB 56.03 kB
/ui/slider-preview 2.01 kB 56.03 kB
/ui/status-announcer 10.87 kB 56.03 kB
/ui/status-indicator 13.30 kB 56.03 kB
/ui/status-indicator-value 1.10 kB —
/ui/thumbnail 10.59 kB 56.03 kB
/ui/time 11.29 kB 56.03 kB
/ui/time-slider 13.38 kB 56.03 kB
/ui/time-slider-chapter-title 9.04 kB 56.03 kB
/ui/time-slider-chapters 9.87 kB 56.03 kB
/ui/title 8.43 kB 56.03 kB
/ui/tooltip 10.13 kB 56.03 kB
/ui/tooltip-label 1.21 kB —
/ui/tooltip-shortcut 1.18 kB —
/ui/volume-indicator 13.25 kB 56.03 kB
/ui/volume-indicator-fill 1.11 kB —
/ui/volume-indicator-value 1.10 kB —
/ui/volume-popover 15.14 kB 56.03 kB
/ui/volume-slider 12.57 kB 56.03 kB
⚛️ @videojs/react — no changes
Presets (7)
Entry Initial Lazy
/video (default) 58.84 kB 56.03 kB
/video (default + hls) 59.33 kB 56.03 kB
/video (minimal) 58.94 kB 56.03 kB
/video (minimal + hls) 59.32 kB 56.03 kB
/audio (default) 45.67 kB 56.03 kB
/audio (minimal) 45.68 kB 56.03 kB
/background 908 B 56.03 kB
Media (22)
Entry Initial
/media/mux-video/hls-js 1.45 kB
/media/mux-video/spf 1.46 kB
/media/mux-audio/hls-js 1.12 kB
/media/mux-audio/spf 1.13 kB
/media/background-video 513 B
/media/cloudflare-video 1.81 kB
/media/dash-video 1.11 kB
/media/hls-audio 22.18 kB
/media/hls-background-video 17.48 kB
/media/hls-video 32.38 kB
/media/hlsjs-video 1.12 kB
/media/mux-audio 1.12 kB
/media/mux-background-video 17.50 kB
/media/mux-video 1.45 kB
/media/native-hls-video 6.32 kB
/media/shaka-video 1.11 kB
/media/spotify-audio 1.89 kB
/media/tiktok-video 1.81 kB
/media/twitch-video 1.84 kB
/media/vimeo-video 1.79 kB
/media/wistia-video 1.41 kB
/media/youtube-video 1.79 kB
Extensions (2)
Entry Initial
/extensions/google-cast 1.77 kB
/extensions/mux-data 1.80 kB
Players (5)
Entry Initial Lazy
/video/player 8.24 kB 56.03 kB
/audio/player 4.39 kB 56.03 kB
/background/player 2.64 kB 56.03 kB
/live-video/player 7.59 kB 56.03 kB
/live-audio/player 4.40 kB 56.03 kB
Skins (18)
Entry Type Initial Lazy
/video/minimal-skin.css css 8.12 kB —
/video/skin.css css 7.81 kB —
/video/minimal-skin js 58.79 kB 56.03 kB
/video/skin js 58.64 kB 56.03 kB
/audio/minimal-skin.css css 5.88 kB —
/audio/skin.css css 5.60 kB —
/audio/minimal-skin js 45.62 kB 56.03 kB
/audio/skin js 45.55 kB 56.03 kB
/background/skin.css css 97 B —
/background/skin js 518 B —
/live-video/minimal-skin.css css 6.60 kB —
/live-video/skin.css css 6.51 kB —
/live-video/minimal-skin js 48.61 kB 56.03 kB
/live-video/skin js 48.64 kB 56.03 kB
/live-audio/minimal-skin.css css 4.58 kB —
/live-audio/skin.css css 4.47 kB —
/live-audio/minimal-skin js 33.79 kB 56.03 kB
/live-audio/skin js 33.79 kB 56.03 kB
UI Components (39)
Entry Initial Lazy
/ui/airplay-button 11.23 kB 56.03 kB
/ui/alert-dialog 5.20 kB 56.03 kB
/ui/audio-track 8.36 kB 56.03 kB
/ui/audio-track-radio-group 10.77 kB 56.03 kB
/ui/buffering-indicator 8.41 kB 56.03 kB
/ui/captions-button 11.19 kB 56.03 kB
/ui/captions-radio-group 10.87 kB 56.03 kB
/ui/cast-button 11.22 kB 56.03 kB
/ui/controls 8.29 kB 56.03 kB
/ui/dialog 5.19 kB 56.03 kB
/ui/error-dialog 12.61 kB 56.03 kB
/ui/fullscreen-button 11.18 kB 56.03 kB
/ui/gesture 8.60 kB 56.03 kB
/ui/hotkey 8.99 kB 56.03 kB
/ui/live-button 9.53 kB 56.03 kB
/ui/menu 22.01 kB 56.03 kB
/ui/mute-button 11.22 kB 56.03 kB
/ui/pip-button 11.19 kB 56.03 kB
/ui/play-button 11.16 kB 56.03 kB
/ui/playback-rate 8.41 kB 56.03 kB
/ui/playback-rate-button 11.14 kB 56.03 kB
/ui/playback-rate-radio-group 10.83 kB 56.03 kB
/ui/popover 9.12 kB 56.03 kB
/ui/poster 8.61 kB 56.03 kB
/ui/quality 8.77 kB 56.03 kB
/ui/quality-radio-group 11.19 kB 56.03 kB
/ui/seek-button 11.18 kB 56.03 kB
/ui/seek-indicator 12.91 kB 56.03 kB
/ui/slider 14.34 kB 56.03 kB
/ui/status-announcer 10.81 kB 56.03 kB
/ui/status-indicator 13.35 kB 56.03 kB
/ui/thumbnail 9.77 kB 56.03 kB
/ui/time 10.60 kB 56.03 kB
/ui/time-slider 16.17 kB 56.03 kB
/ui/title 7.88 kB 56.03 kB
/ui/tooltip 9.98 kB 56.03 kB
/ui/volume-indicator 13.39 kB 56.03 kB
/ui/volume-popover 15.53 kB 56.03 kB
/ui/volume-slider 12.96 kB 56.03 kB
🧩 @videojs/core — no changes
Entries (76)
Entry Initial Lazy
. 13.39 kB —
/dom 23.48 kB 56.03 kB
/vjsc 1.90 kB —
/i18n 3.21 kB 56.03 kB
/i18n/locales/all 33.91 kB —
/i18n/locales/ar 1.16 kB —
/i18n/locales/az 1.08 kB —
/i18n/locales/bg 1.29 kB —
/i18n/locales/bn 1.25 kB —
/i18n/locales/bs 1.02 kB —
/i18n/locales/ca 1.04 kB —
/i18n/locales/cs 1.10 kB —
/i18n/locales/cy 1.02 kB —
/i18n/locales/da 984 B —
/i18n/locales/de 1.06 kB —
/i18n/locales/el 1.42 kB —
/i18n/locales/en 801 B —
/i18n/locales/es 999 B —
/i18n/locales/et 1.02 kB —
/i18n/locales/eu 1.04 kB —
/i18n/locales/fa 1.21 kB —
/i18n/locales/fi 1.05 kB —
/i18n/locales/fr 1.01 kB —
/i18n/locales/gd 1.09 kB —
/i18n/locales/gl 1017 B —
/i18n/locales/he 1.10 kB —
/i18n/locales/hi 1.25 kB —
/i18n/locales/hr 1.05 kB —
/i18n/locales/hu 1.10 kB —
/i18n/locales/id 953 B —
/i18n/locales/it 1.01 kB —
/i18n/locales/ja 1.16 kB —
/i18n/locales/ko 1.08 kB —
/i18n/locales/lt 1.04 kB —
/i18n/locales/lv 1.09 kB —
/i18n/locales/mr 1.23 kB —
/i18n/locales/nb 990 B —
/i18n/locales/ne 1.23 kB —
/i18n/locales/nl 1.01 kB —
/i18n/locales/nn 983 B —
/i18n/locales/oc 1.05 kB —
/i18n/locales/pl 1.11 kB —
/i18n/locales/pt 1.02 kB —
/i18n/locales/pt-BR 1.02 kB —
/i18n/locales/pt-PT 1.02 kB —
/i18n/locales/ro 1.04 kB —
/i18n/locales/ru 1.36 kB —
/i18n/locales/sk 1.10 kB —
/i18n/locales/sl 1.04 kB —
/i18n/locales/sr 1.05 kB —
/i18n/locales/sv 1.01 kB —
/i18n/locales/te 1.29 kB —
/i18n/locales/th 1.20 kB —
/i18n/locales/tr 1.00 kB —
/i18n/locales/uk 1.37 kB —
/i18n/locales/vi 1.10 kB —
/i18n/locales/zh 1.01 kB —
/i18n/locales/zh-CN 1.01 kB —
/i18n/locales/zh-TW 1.02 kB —
/i18n/text/airplay 101 B —
/i18n/text/buttons 137 B —
/i18n/text/captions 93 B —
/i18n/text/cast 114 B —
/i18n/text/common 90 B —
/i18n/text/container 75 B —
/i18n/text/errors 285 B —
/i18n/text/fullscreen 98 B —
/i18n/text/live 126 B —
/i18n/text/menu 249 B —
/i18n/text/pip 101 B —
/i18n/text/playback 80 B —
/i18n/text/seek 105 B —
/i18n/text/slider 65 B —
/i18n/text/status 222 B —
/i18n/text/time 322 B —
/i18n/text/volume 133 B —
🏷️ @videojs/element — no changes
Entries (2)
Entry Initial
. 1.05 kB
/context 943 B
📦 @videojs/store — no changes
Entries (3)
Entry Initial
. 1.72 kB
/html 703 B
/react 511 B
🔧 @videojs/utils — no changes
Entries (13)
Entry Initial
/array 271 B
/dom 5.25 kB
/events 320 B
/function 414 B
/i18n 249 B
/jwt 176 B
/object 535 B
/predicate 297 B
/percent 281 B
/string 239 B
/style 212 B
/time 1018 B
/number 199 B
📦 @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 changes
Entries (3)
Entry Initial
. 3.16 kB
/dom 4.12 kB
/media-tracks 2.05 kB
📦 @videojs/mux — no changes
📦 @videojs/mux-audio — no changes
Entries (2)
Entry Initial
. 136.18 kB
/spf 22.67 kB
📦 @videojs/mux-data — no changes
📦 @videojs/mux-video — no changes
Entries (2)
Entry Initial
. 136.17 kB
/spf 32.79 kB
📦 @videojs/native-hls-video — no changes
📦 @videojs/shaka-video — no changes
📦 @videojs/spf — no changes
Entries (7)
Entry Initial
. 4.55 kB
/dom 7.67 kB
/hls 28.08 kB
/media-tracks 507 B
/hls-background-video 16.46 kB
/hls-audio 21.27 kB
/hls-video 31.46 kB
📦 @videojs/spotify-audio — no changes
📦 @videojs/tiktok-video — no changes
📦 @videojs/twitch-video — no changes
📦 @videojs/other — no changes
Entries (3)
Entry Initial Lazy
video.js 73.42 kB 56.03 kB
video.js/package.json 608 B —
video.js/errors 1.03 kB —
📦 @videojs/vimeo-video — no changes
📦 @videojs/wistia-video — no changes
Entries (2)
Entry Initial
. 1.92 kB
/helpers 1.77 kB
📦 @videojs/youtube-video — no changes

ℹ️ How to interpret

Each 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 pnpm size locally to check current initial sizes.

@mihar-22
mihar-22 force-pushed the t3code/vidstack-migration-guide branch from c30adc1 to ac231da Compare September 30, 2026 03:59
@mihar-22
mihar-22 marked this pull request as ready for review September 30, 2026 21:04
@mihar-22
mihar-22 force-pushed the t3code/vidstack-migration-guide branch from 9348569 to 90eafc9 Compare September 30, 2026 21:20

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ 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 decepulis left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
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.
@mihar-22
mihar-22 merged commit a30932a into main Oct 1, 2026
34 of 36 checks passed
@mihar-22
mihar-22 deleted the t3code/vidstack-migration-guide branch October 1, 2026 03:10
@github-actions github-actions Bot mentioned this pull request Oct 1, 2026

This branch was successfully deployed

1 active deployment
Preview — 17b42b14 Deployed Oct 1, 2026 by vercel[bot]
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Migration Guide from Vidstack

2 participants