From bc85f96e1c50816f7a48c160621bb477a314bdd8 Mon Sep 17 00:00:00 2001 From: Rahim Date: Mon, 28 Sep 2026 17:54:54 -0700 Subject: [PATCH 01/17] docs(site): add the vidstack migration guide 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 --- site/integrations/llms-markdown.ts | 4 + site/integrations/tests/llms-markdown.test.ts | 3 + .../InstallationMigrationNotice.astro | 5 +- ...-10-videojs-v10-beta-hello-world-again.mdx | 2 +- .../docs/guides/migrate-from-vidstack.mdx | 1360 +++++++++++++++++ site/src/content/docs/guides/v10-roadmap.mdx | 2 +- site/src/docs.config.ts | 1 + 7 files changed, 1374 insertions(+), 3 deletions(-) create mode 100644 site/src/content/docs/guides/migrate-from-vidstack.mdx diff --git a/site/integrations/llms-markdown.ts b/site/integrations/llms-markdown.ts index 3258bc5aee..85142536c8 100644 --- a/site/integrations/llms-markdown.ts +++ b/site/integrations/llms-markdown.ts @@ -1107,6 +1107,10 @@ export function generateDocsIndex( content += `> The \`video.js\` package on npm is still Video.js 8. Video.js 10 ships as \`@videojs/${framework}\`; to move existing Video.js 8 code, read ${siteUrl}/docs/framework/${framework}/guides/migrate-from-video-js-8.md\n\n`; + const vidstackPackage = framework === 'react' ? '@vidstack/react' : 'vidstack'; + + content += `> Vidstack Player is in security-only maintenance. To move existing \`${vidstackPackage}\` code, read ${siteUrl}/docs/framework/${framework}/guides/migrate-from-vidstack.md\n\n`; + content += `> Print version-matched installation options without changing files: \`npx @videojs/cli agents init\`, then pass \`--framework ${framework}\` with the other choices. Installation guide index: ${siteUrl}/docs/guides/installation.md\n\n`; // Get sidebar filtered for this framework (production only) diff --git a/site/integrations/tests/llms-markdown.test.ts b/site/integrations/tests/llms-markdown.test.ts index 6a41372a76..b130f05f4e 100644 --- a/site/integrations/tests/llms-markdown.test.ts +++ b/site/integrations/tests/llms-markdown.test.ts @@ -460,6 +460,9 @@ describe('generateDocsIndex', () => { expect(index).toContain( '> The `video.js` package on npm is still Video.js 8. Video.js 10 ships as `@videojs/html`; to move existing Video.js 8 code, read https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8.md\n' ); + expect(index).toContain( + '> Vidstack Player is in security-only maintenance. To move existing `vidstack` code, read https://videojs.org/docs/framework/html/guides/migrate-from-vidstack.md\n' + ); expect(index).toContain( '## Guides\n\n' + 'Installation, migration, concepts, playback guides, customization, and tooling for Video.js.\n\n' + diff --git a/site/src/components/installation/InstallationMigrationNotice.astro b/site/src/components/installation/InstallationMigrationNotice.astro index 27f841adc6..08fd869b39 100644 --- a/site/src/components/installation/InstallationMigrationNotice.astro +++ b/site/src/components/installation/InstallationMigrationNotice.astro @@ -18,6 +18,9 @@ const guide = framework ? `${FRAMEWORK_LABELS[framework]} migration guide` : 'mi >, Mux Player, Plyr, or Media Chrome. Each maps your + >, Media Chrome, or Vidstack. Each maps your existing setup onto Video.js v10 instead of starting from scratch. diff --git a/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx b/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx index da028d16ff..70b4d6ff4d 100644 --- a/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx +++ b/site/src/content/blog/2026-03-10-videojs-v10-beta-hello-world-again.mdx @@ -362,7 +362,7 @@ If you're starting something new, this is a good time to try v10. Go to [videojs If you're running a previous version in production, sit tight. We'll have migration guides before we ask you to move. ## What's coming diff --git a/site/src/content/docs/guides/migrate-from-vidstack.mdx b/site/src/content/docs/guides/migrate-from-vidstack.mdx new file mode 100644 index 0000000000..b24a37f729 --- /dev/null +++ b/site/src/content/docs/guides/migrate-from-vidstack.mdx @@ -0,0 +1,1360 @@ +--- +title: Migrate from Vidstack +description: Move a Vidstack Player integration to Video.js 10, mapping the player, providers, layouts, and media store onto composed components +--- + +import Aside from '@/components/Aside.astro'; +import DocsLink from '@/components/docs/DocsLink.astro'; +import FrameworkCase from '@/components/docs/FrameworkCase.astro'; + +Vidstack Player gives you one `` that holds state, picks a provider from `src`, and hosts a layout you configure with props, slots, and CSS variables. + +Video.js 10 grew out of the same ideas: composed, accessible components, one store per player, and state you can style against. The teams behind Vidstack, Plyr, Media Chrome, and Video.js now focus their work on Video.js. The code is new, though, and the jobs `` did are split across smaller pieces. Most of this guide is about where each Vidstack concept moved. + + + + + +## Migrate with a coding agent + +The [Video.js skill](https://github.com/videojs/skills) teaches coding agents how Video.js 10 is composed and points them at documentation that matches your installed version. Paste this prompt into your agent to install the skill and start the migration: + + +```text +Install the Video.js skill: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill to migrate this project from @vidstack/react to @videojs/react. Follow the Vidstack migration guide that ships with the package at node_modules/@videojs/react/docs/guides/migrate-from-vidstack.md. Until @videojs/react is installed, read https://videojs.org/docs/framework/react/guides/migrate-from-vidstack.md instead. When installation details are needed, run `npx @videojs/cli agents init` to print version-matched instructions without changing files. Before changing code, compare the Vidstack features this project uses with the guide's "Known gaps" section and tell me about any that have no Video.js equivalent. +``` + + + +```text +Install the Video.js skill: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill to migrate this project from vidstack to @videojs/html. Follow the Vidstack migration guide that ships with the package at node_modules/@videojs/html/docs/guides/migrate-from-vidstack.md. Until @videojs/html is installed, read https://videojs.org/docs/framework/html/guides/migrate-from-vidstack.md instead. When installation details are needed, run `npx @videojs/cli agents init` to print version-matched instructions without changing files. Before changing code, compare the Vidstack features this project uses with the guide's "Known gaps" section and tell me about any that have no Video.js equivalent. +``` + + +The installed copy of this guide matches your package version, so the agent doesn't rely on training data that mostly describes older players. See Build with AI to install the skill yourself or give your tool the docs another way. + +## Before you migrate + +Two checks save the most time. + +**Compare your features with [Known gaps](#known-gaps).** Saved preferences, the chapters menu, caption style settings, audio gain, clipping, and non-VTT captions have no Video.js equivalent yet. If your player depends on one of them, that shapes your timeline more than anything else in this guide. + + +**Remove Vidstack in the same change that adds Video.js 10.** Both libraries register `media-play-button`, `media-controls`, `media-time-slider`, and 21 other custom element names. The browser keeps whichever definition loads first, so the two can't run on the same page. Remove Vidstack's imports, CDN scripts, and stylesheets before you add Video.js. + + + +**Migrate one player at a time if you need to.** Neither `@vidstack/react` nor `@videojs/react` registers custom elements, so both can render in the same app while you move players across. Remove `@vidstack/react` and its stylesheets once nothing imports them. + + +## Three pieces instead of one + +In Vidstack, `` does most of the work. It holds state, selects and loads a provider, acts as the box you size and take fullscreen, carries the state attributes you style against, and listens for keyboard shortcuts. + +Video.js 10 splits those jobs: + +**The player** holds state and hands it to everything inside it. It draws nothing and takes no layout. Which state it holds depends on the features it's built from. + +**The media** plays the video. This is where Vidstack's *provider* went, except you choose it yourself: a plain `