@videojs/react 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/guides/browser-support.md

@@ -0,0 +1,145 @@
+# Browser support
+
+Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
+
+Video.js 10 supports the **latest two stable versions** of Chrome, Edge, Firefox, Safari, and Safari on iOS. This page shows the versions that means today, what the packaged skins need from a browser, and how to reach older ones.
+
+## Browser baseline
+
+The build reads the policy from a [browserslist](https://browsersl.ist) query in the repository, and this page resolves the same query when the docs are built:
+
+*Supported browsers and the versions the support policy resolves to today*
+
+| Browser | Versions |
+| --- | --- |
+| Chrome | 150 and 151 |
+| Edge | 150 and 151 |
+| Firefox | 153 and 154 |
+| Safari | 26.5 and 26.6 |
+| Safari on iOS | 26.5 and 26.6 |
+
+These are the versions we test in and fix bugs for. We build directly on the web platform, with [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope), [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries), and [anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning), and we do not hold a feature back to keep older versions working. Older versions often work anyway:
+
+In practice the packaged skins render in Chrome 120, Edge 120, Firefox 146, Safari 17.4, and Safari on iOS 17.4 and later. Those versions account for 89.2% of global web usage according to [caniuse-lite](https://github.com/browserslist/caniuse-lite) 1.0.30001810, and this figure updates when we update that data.
+
+## CSS requirements
+
+The packaged skins are generated CSS, and a handful of newer features hold a skin together. **Required** features have no fallback: without them the player shows no component styling, and `@scope` alone sets the floor. **Degrades** features lose one visual detail. **Has a fallback** features sit inside [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports); anchor positioning falls back to positions computed in JavaScript.
+
+The table reads the first fully supporting version of each feature from [caniuse-lite](https://github.com/browserslist/caniuse-lite) when the docs build, and feature names link to [caniuse.com](https://caniuse.com/). The **effective floor** is the newest required version in each column.
+
+*First browser version that fully supports each CSS feature the packaged skins use, with the share of global web usage on supporting browsers. Feature names link to their caniuse.com support data. "Not supported" means the browser has no full support. Paired browsers share a column and show two values only when they differ. The effective floor row is the newest required version in each column.*
+
+| Feature | Chrome and Edge | Firefox | Safari and iOS | Global support |
+| --- | --- | --- | --- | --- |
+| [`@scope`](https://caniuse.com/css-cascade-scope) Required. No component styling. | 118 | 146 | 17.4 | 90.0% |
+| [`CSS nesting`](https://caniuse.com/css-nesting) Required. No component styling. | 120 | 117 | 17.2 | 90.7% |
+| [`@layer`](https://caniuse.com/css-cascade-layers) Required. No component styling. | 99 | 97 | 15.4 | 95.3% |
+| [`:has()`](https://caniuse.com/css-has) Required. Menu and slider focus states are lost. | 105 | 121 | 15.4 | 94.1% |
+| [`@container`](https://caniuse.com/css-container-queries) Required. Controls do not adapt to player width. | 106 | 110 | 16 | 94.0% |
+| [`Media query range syntax`](https://caniuse.com/css-media-range-syntax) Required. Large-screen sizing is lost. | 104 | 63 | 16.4 | 94.0% |
+| [`:dir()`](https://caniuse.com/css-dir-pseudo) Required. Right-to-left layout is lost. | 120 | 17 | 16.4 | 91.4% |
+| [`Relative color syntax`](https://caniuse.com/css-relative-colors) Degrades. Adaptive shadows are lost. | 131 | 133 | 18 | 85.7% |
+| [`scrollbar-color and scrollbar-width`](https://caniuse.com/css-scrollbar) Degrades. Menus show default scrollbars. | 121 | 64 | 26.2 | 85.6% |
+| [`backdrop-filter`](https://caniuse.com/css-backdrop-filter) Degrades. Surfaces lose their blur. | 76 / 17 | 103 | 9 | 95.7% |
+| [`Anchor positioning`](https://caniuse.com/css-anchor-positioning) Has a fallback. Popups are positioned by JavaScript. | 125 | 147 | 26 | 84.1% |
+| Effective floor | 120 | 146 | 17.4 | 89.2% |
+
+A few features have no caniuse entry. [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) is required but older than the floor (Chrome 111, Firefox 113, Safari 15.4). [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark), [relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors), [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property), and [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/contrast-color) each degrade on their own; set `--media-accent-text-color` from [Customize skins](./customize-skins.md) if you support browsers without `contrast-color()`. [Firefox ESR](https://www.mozilla.org/en-US/firefox/enterprise/) releases older than 146 lack `@scope`, so the skins render unstyled there.
+
+The JavaScript has a lower floor: ES2022 syntax, with newer APIs feature-detected, so it runs in Chrome 102, Firefox 112, and Safari 16.4 or later. The stylesheet decides whether an older browser shows a working player.
+
+### Support older browsers
+
+To reach browsers below the floor, recompile the skin stylesheet with fallbacks. Only a stylesheet your build processes can be recompiled.
+
+Skins are stylesheets you import, such as `@videojs/react/video/skin.css`, so your bundler’s CSS pipeline already sees them and nothing else changes.
+
+[lightningcss](https://lightningcss.dev/transpilation.html) and [postcss-preset-env](https://preset-env.cssdb.org/) both read a browserslist query and add what those browsers lack: they flatten nesting and rewrite `:dir()`, range media queries, `light-dark()`, and `oklch()` in ordinary declarations, and add vendor prefixes. Neither rewrites `@scope` or `:scope`, so a small plugin flattens each block into descendant selectors prefixed with [`:where(root)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which adds no specificity. The PostCSS version, picked up by Vite, Next.js, and most bundlers from `postcss.config.mjs`:
+
+```bash
+npm install --save-dev postcss postcss-preset-env postcss-selector-parser
+```
+
+**postcss.config.mjs**
+
+```js
+import presetEnv from 'postcss-preset-env';
+import selectorParser from 'postcss-selector-parser';
+
+/** Rewrite `@scope (<root>) { … }` into descendant selectors that older browsers understand. */
+function flattenScope() {
+  const rewrite = (selector, root) =>
+    selectorParser((selectors) => {
+      selectors.each((sel) => {
+        let referencesRoot = false;
+
+        sel.walk((node) => {
+          if (node.type === 'nesting' || (node.type === 'pseudo' && node.value === ':scope')) {
+            node.replaceWith(selectorParser.string({ value: root }));
+            referencesRoot = true;
+          }
+        });
+
+        if (!referencesRoot) {
+          sel.prepend(selectorParser.combinator({ value: ' ' }));
+          sel.prepend(selectorParser.string({ value: `:where(${root})` }));
+        }
+      });
+    }).processSync(selector);
+
+  return {
+    postcssPlugin: 'flatten-scope',
+    OnceExit(css) {
+      const scopes = [];
+      css.walkAtRules('scope', (atRule) => scopes.push(atRule));
+
+      // Innermost first, so a nested scope is flattened before its parent prefixes it.
+      for (const atRule of scopes.reverse()) {
+        const match = /^\(\s*(.+?)\s*\)\s*$/.exec(atRule.params);
+        if (!match || /\)\s*to\s*\(/.test(atRule.params)) continue;
+
+        atRule.walkRules((rule) => {
+          rule.selectors = rule.selectors.map((selector) => rewrite(selector.trim(), match[1]));
+        });
+        atRule.replaceWith(atRule.nodes);
+      }
+    },
+  };
+}
+flattenScope.postcss = true;
+
+export default {
+  plugins: [flattenScope(), presetEnv({ browsers: 'baseline widely available', stage: 2 })],
+};
+```
+
+The result renders in Chrome 111, Firefox 121, and Safari 16.4 or later, the floor [Tailwind CSS 4 documents](https://tailwindcss.com/docs/compatibility#browser-support), because `:has()`, `@container`, `@layer`, and `color-mix()` have no fallback. Flattening `@scope` trades scope proximity for source order; the packaged skins never nest a component inside itself, so the output matches. Run `npx browserslist "baseline widely available"` to see what the query resolves to today, or pick another query for your audience.
+
+## Rendering contexts
+
+### WebViews
+
+A WebView is a browser engine embedded inside a native app. WebViews on iOS ([WKWebView](https://developer.apple.com/documentation/webkit/wkwebview)) and Android ([Android WebView](https://developer.android.com/reference/android/webkit/WebView)) can behave differently from the full browser; autoplay policies, fullscreen APIs, and hardware acceleration can vary.
+
+Video.js 10 targets standard browser environments. If you embed a player inside a native app, test it on each platform and WebView version you support.
+
+### Progressive Web Apps
+
+Installed Progressive Web Apps (PWAs) use the browser engine, but their standalone display mode and platform policies can affect fullscreen, media sessions, and other browser integration. Test playback both in a browser tab and in the installed app.
+
+### Smart TVs and set-top boxes
+
+TV platforms run embedded browsers with limited standards support. Video.js 10’s core is not tied to any specific platform, which makes future TV adapters possible, but TV is not a supported target today.
+
+### Server-side rendering
+
+Video.js components render valid markup on the server. Interactivity — state management, media playback, and event handling — requires the browser and kicks in after hydration.
+
+## Related pages
+
+### Guides
+
+- [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

package/docs/guides/build-with-ai.md

@@ -0,0 +1,167 @@
+# Build with AI
+
+Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
+
+The [Video.js skill](https://github.com/videojs/skills) gives coding agents the context they need to build, customize, debug, and migrate Video.js players. It teaches the agent how Video.js 10 is composed, then points it to documentation that matches the version installed in your project.
+
+## AI Quickstart
+
+Paste this prompt into your coding agent:
+
+```
+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 for this project. When installation details are needed, run `npx @videojs/cli agents init --framework react` to print the version-matched choices and instructions without changing files.
+```
+
+## Video.js Skill
+
+The skill contains guidance and Markdown references. It does not install Video.js, run background services, or connect to an account.
+
+### Install the skill
+
+Follow the steps for your coding agent. To print the same steps in a terminal, run:
+
+**Terminal**
+
+```sh
+npx @videojs/cli agents skills
+```
+
+Add `--agent claude-code,cursor` to print only those agents. `--scope project` or `--scope local` changes the Claude Code installation scope from its `user` default, and `--global` adds `-g` to the `skills` installer command. Like `agents init`, the command only prints instructions.
+
+#### Codex
+
+Add the Video.js plugin marketplace, then install the plugin:
+
+**Terminal**
+
+```sh
+codex plugin marketplace add videojs/skills
+codex plugin add videojs@videojs
+```
+
+Start a new Codex session after installation.
+
+#### Claude Code
+
+Add the Video.js plugin marketplace, then install the plugin:
+
+**Terminal**
+
+```sh
+claude plugin marketplace add videojs/skills
+claude plugin install videojs@videojs
+```
+
+Start a new Claude Code session, or run `/reload-plugins` in the current session.
+
+You can invoke the skill directly with `/videojs:videojs`.
+
+#### VS Code
+
+Enable `chat.plugins.enabled`, run **Chat: Install Plugin From Source** from the Command Palette, and enter:
+
+```text
+https://github.com/videojs/skills
+```
+
+Start a new VS Code session after installation, or reload the window.
+
+#### Cursor
+
+Open **Customize**, select **Plugins**, choose **From GitHub Repository**, and enter:
+
+```text
+https://github.com/videojs/skills
+```
+
+Start a new Cursor session after installation, or reload the window.
+
+#### Other coding agents
+
+Use the open `skills` installer and select your agent when prompted:
+
+**Terminal**
+
+```sh
+npx skills add https://github.com/videojs/skills
+```
+
+Start a new session in your coding agent after installation.
+
+Project-local installation is the default. Add `-g` if you want the skill available in every project.
+
+To skip the prompts, name the agent and confirm up front, for example `npx skills add https://github.com/videojs/skills --agent <agent> --yes`.
+
+### Use the skill
+
+Ask for the player you want to build or the problem you want to solve. For example:
+
+> Add an HLS player with captions and a quality menu to the product page using Video.js.
+
+> Play this Mux playback ID in our Next.js app with Video.js, with Mux Data turned on.
+
+> Migrate this Video.js 8 embed to Video.js 10 in React.
+
+The skill checks your framework and installation method before choosing player, skin, and media code. It also checks imports and playback setup against current documentation before handing the work back.
+
+### How skills find docs
+
+The skill uses documentation in this order:
+
+1. **Version-matched installation instructions.** `npx @videojs/cli agents init` lists valid choices for every framework. Adding flags prints one complete installation plan. When the project already has a different `@videojs/react` or `@videojs/html` version, the plan names the pinned command for that release. The command only returns instructions; it does not prompt, install packages, or write files.
+2. **Installed package docs.** `node_modules/@videojs/react/docs/llms.txt` and `node_modules/@videojs/html/docs/llms.txt` index the docs shipped with each package version. These files work offline and match the code in your project.
+3. **Live docs.** If commands cannot run, the skill reads the relevant [React](../llms.txt) or [HTML](https://videojs.org/docs/framework/html/llms.txt) documentation index, then follows it to the matching installation guide.
+4. **Installed types.** If the docs are unavailable, the skill checks package exports and TypeScript declarations instead of guessing version-specific APIs.
+
+This order matters because most model training data describes Video.js 8. Video.js 10 has a different component model, package structure, and installation flow.
+
+The old `npx @videojs/cli docs` workflow was removed. `@videojs/cli` now contains only `agents init` and `agents skills`, in a single file with no dependencies, so running it does not download the player packages.
+
+### Troubleshoot
+
+If your agent does not use the skill, start a new session or reload plugins, then ask it to use the Video.js skill explicitly. If it writes `videojs()`, `data-setup`, `registerPlugin`, or other Video.js 8 APIs, ask it to read the installed `llms.txt` before changing code.
+
+Report problems with the skill in the [videojs/skills repository](https://github.com/videojs/skills/issues). Report package and documentation problems in [videojs/v10](https://github.com/videojs/v10/issues).
+
+## Use the docs
+
+You can still provide documentation directly when a tool cannot install skills.
+
+### Copy one page
+
+Each docs page has a **Copy page** menu. Copy the Markdown, open the `.md` version, or send the page to ChatGPT or Claude.
+
+### Open a Markdown URL
+
+Add `.md` to any docs URL. For this page, use:
+
+```text
+https://videojs.org/docs/framework/react/guides/build-with-ai.md
+```
+
+Each docs page also advertises its Markdown URL as an alternate format so compatible tools can discover it.
+
+### Request Markdown
+
+Request the normal docs URL with an `Accept: text/markdown` header:
+
+**Terminal**
+
+```sh
+curl -H "Accept: text/markdown" \
+  https://videojs.org/docs/framework/react/guides/build-with-ai
+```
+
+### Start from llms.txt
+
+[`videojs.org/docs/framework/react/llms.txt`](../llms.txt) lists every React guide and reference page with a short description. Give the index to your tool, then load only the pages the task needs.
+
+The `llms-full.txt` files contain the complete documentation corpus. Use them only when your tool requires one file because they are larger than most useful task contexts.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Architecture](./architecture.md): How Video.js players are structured — state, UI, media, and extensions
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.

package/docs/guides/build-your-own-component.md

@@ -0,0 +1,182 @@
+# Build your own UI component
+
+Create custom player controls that read state, dispatch actions, and stay accessible.
+
+Custom components subscribe to player state and dispatch actions, like built-in controls.
+
+## You might not need a custom component
+
+Before building from scratch, check if an existing approach covers your use case:
+
+- **Change what a control renders**: use the `render` prop on any built-in component. See [UI components](./ui-components.md).
+- **Restyle a control**: use CSS custom properties and data attributes. See [UI components](./ui-components.md).
+- **Rearrange or remove controls**: add the skin source to your project, then modify it. See [Customize skins](./customize-skins.md#style-skin-source).
+
+Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+## Place your component in the player
+
+Your component needs to be inside [`<Player>`](../reference/components/player.md) to access state. Place it inside [`<Container>`](../reference/components/player-container.md) if it should also participate in fullscreen and respond to user activity:
+
+```tsx
+import { Container } from '@videojs/react';
+
+<Player>
+  <Container>
+    <VideoSkin>
+      <Video src="video.mp4" />
+    </VideoSkin>
+    <SkipIntroButton />
+  </Container>
+</Player>
+```
+
+## Full example
+
+A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
+
+**SkipIntroButton.tsx**
+
+```tsx
+// The preset's usePlayer is typed for its feature bundle
+import { usePlayer } from '@videojs/react/video';
+
+export function SkipIntroButton() {
+  const store = usePlayer();
+  const currentTime = usePlayer((s) => s.currentTime);
+  const paused = usePlayer((s) => s.paused);
+
+  const visible = currentTime < 30 && !paused;
+
+  return (
+    <button
+      className="skip-intro-button"
+      onClick={() => store.seek(30)}
+      aria-label="Skip intro"
+      // `undefined` removes the attribute; `false` would render data-visible="false"
+      data-visible={visible || undefined}
+      tabIndex={visible ? 0 : -1}
+    >
+      Skip intro
+    </button>
+  );
+}
+```
+
+**SkipIntroButton.css**
+
+```css
+.skip-intro-button {
+  position: absolute;
+  bottom: 5rem;
+  right: 1rem;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 200ms;
+}
+
+.skip-intro-button[data-visible] {
+  opacity: 1;
+  pointer-events: auto;
+}
+```
+
+Your component needs to be inside a player, such as [`<VideoPlayer>`](../reference/components/player.md), to access state. Place it inside [`<Container>`](../reference/components/player-container.md) if it should also participate in fullscreen and respond to user activity:
+
+```tsx
+import { Container } from '@videojs/react';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/skin.css';
+
+import { SkipIntroButton } from './SkipIntroButton';
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <VideoSkin>
+          <Video src="video.mp4" />
+        </VideoSkin>
+        <SkipIntroButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+Custom components read player state and dispatch actions through [features](./features.md). Each feature exposes a set. Here are some features you might reach for first:
+
+| State | Actions | Feature |
+| --- | --- | --- |
+| `paused`, `ended` | `play()`, `pause()` | [Playback](../reference/api/feature-playback.md) |
+| `currentTime`, `duration` | `seek()` | [Time](../reference/api/feature-time.md) |
+| `volume`, `muted` | `setVolume()`, `toggleMuted()` | [Volume](../reference/api/feature-volume.md) |
+| `fullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](../reference/api/feature-fullscreen.md) |
+
+The API reference lists every feature with the state and actions it adds.
+
+Access state and actions with the [`usePlayer`](../reference/api/use-player.md) hook from your player’s preset. It knows which features that preset has, so state and actions are typed. (The standalone `usePlayer` export from `@videojs/react` returns an untyped store, so its values are `unknown` in TypeScript.) If you built the player with a custom feature set through [`createPlayer`](../reference/api/create-player.md) — the escape hatch for custom feature sets — use the `usePlayer` it returns instead.
+
+```tsx
+import { usePlayer } from '@videojs/react/video';
+
+// Subscribe to state — re-renders only when selected values change
+const paused = usePlayer((s) => s.paused);
+const currentTime = usePlayer((s) => s.currentTime);
+
+// Get the store for dispatching actions (does not subscribe)
+const store = usePlayer();
+
+await store.play();
+store.setVolume(0.5);
+store.seek(30);
+```
+
+Custom controls also need real button semantics — the examples above set the accessible name and keyboard focus by hand.
+
+- [Learn more about accessibility in video players](./accessibility.md)
+
+## Availability and constraints
+
+- Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
+- Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](./features.md) for details.
+
+## Common variations
+
+Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
+
+### Change what a built-in control renders
+
+Use the `render` prop on any built-in component. See [UI components](./ui-components.md).
+
+### Restyle a control
+
+Use CSS custom properties and data attributes. See [UI components](./ui-components.md).
+
+### Rearrange or remove controls
+
+Add the skin source to your project and modify it. See [Customize skins](./customize-skins.md#style-skin-source).
+
+## Troubleshooting
+
+### State and actions are typed as `unknown`
+
+You’re using the standalone `usePlayer` export, which doesn’t know which features your player has. Import `usePlayer` from your player’s preset (for example `@videojs/react/video`), or use the hook returned by `createPlayer` if you built the player with a custom feature set.
+
+### The component renders but never updates
+
+The component sits outside the player (such as `<VideoPlayer>`), so `usePlayer` has no store to subscribe to.
+
+## Related pages
+
+### API
+
+- [usePlayer](../reference/api/use-player.md): Hook to access the player store from within a Player
+- [createPlayer](../reference/api/create-player.md): Factory function that creates a typed Player component and hooks
+- [Container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+### Guides
+
+- [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions

package/docs/guides/bundlers.md

@@ -0,0 +1,50 @@
+# Bundlers
+
+Bundler requirements for Video.js package exports, CSS, and wrapper libraries
+
+Before the browser runs your application, a bundler such as Vite combines its imports into files the browser can load. Your bundler must understand the import paths published by Video.js packages.
+
+## Package exports
+
+Each Video.js package has an `exports` field in its `package.json`. This field lists the import paths that applications and libraries can use, such as `@videojs/react/video` and `@videojs/react/live-video`.
+
+If an older bundler reports that one of these paths is missing or not exported, upgrade the bundler before adding an alias that bypasses the package’s public API.
+
+## Vite compatibility
+
+Use Vite 4.1 or later; Video.js has been tested through Vite 8. Earlier versions can’t resolve exported stylesheets such as `@videojs/react/video/skin.css`.
+
+React skins ship their stylesheet as a separate export: an application that renders `VideoSkin` from `@videojs/react/video` also imports `@videojs/react/video/skin.css`, so this limitation applies to every React application that uses a packaged skin.
+
+## Externalize Video.js in a wrapper library
+
+You can skip this section when building an application.
+
+If you publish a library that expects its users to install Video.js separately, leave Video.js out of your library’s bundle. Rollup calls a dependency left out of the bundle **external**.
+
+Rollup’s array form matches only the exact package name, so `external: ['@videojs/react']` misses imports such as `@videojs/react/video`.
+
+Match the package name and everything below it instead:
+
+**rollup.config.js**
+
+```js
+const videojsPeers = ['@videojs/react'];
+
+export default {
+  external(id) {
+    return videojsPeers.some(
+      (packageName) => id === packageName || id.startsWith(`${packageName}/`)
+    );
+  }
+};
+```
+
+Add every `@videojs/*` package your library imports directly to `videojsPeers` and list it in `peerDependencies`.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [TypeScript](./typescript.md): TypeScript version and module resolution requirements for Video.js packages