First off, thank you for taking the time to contribute to Video.js 10 ❤️ Your input helps shape the next generation of open web media players.

Video.js is a free and open source library, and we appreciate any help you're willing to give - whether it's fixing bugs, improving documentation, or suggesting new features. Contributions and project decisions are overseen by the Video.js Technical Steering Committee (TSC).

Video.js 10 is set up a monorepo using pnpm workspaces. As such, most scripts run will be done from the project/workspace root. Unless otherwise specified, assume commands and similar should be run from the root directory.

You’ll need the following installed:

• Node.js (≥ 22.19.0)
• Git
• PNPM (≥ 10.17.0)
• Volta or NVM (we recommend Volta for automatic Node management)
• Claude Code (optional, for AI-assisted development)

1. Fork on GitHub.
2. Clone your fork locally and set up upstream tracking:

git clone https://github.com/{your-github-username}/v10.git
cd v10

git remote add upstream git@github.com:videojs/v10.git
git fetch upstream
git branch --set-upstream-to=upstream/main main

To update your local main branch later:

git fetch upstream
git checkout main
git pull upstream main

pnpm install

This also creates symlink aliases (.opencode, agents, AGENTS.md) so that AI coding tools other than Claude Code can discover project instructions.

Then build all workspace packages:

pnpm build:packages

ℹ️ VS Code Users: the project may suggest extensions to enhance the developer experience. If imports like react are not resolving, set your TS version to the workspace one: CMD/CTRL + Shift + P → TypeScript: Select TypeScript Version → Use Workspace Version.

To run the workspace in development mode:

pnpm dev

This will run the entire workspace in developer mode, meaning all applications (examples and website) will also be started on their respective ports.

pnpm dev:site       # just the documentation site
pnpm dev:packages   # just the library packages (no apps)
pnpm dev:sandbox    # just the sandbox playground

See Manual Testing with the Sandbox for how to use the sandbox to exercise player changes in the browser.

Sometimes you may want to do (non-dev) builds, say, to validate the full build process or evaluate production artifacts.

pnpm build:packages

To build the sandbox (and its package dependencies):

pnpm build:sandbox

To build all workspace packages and applications:

pnpm build

For the bulk of our core code, we use Biome. Between IDE configs, pre-commit hooks, and manual CLI fixes, many styling and linting issues should get caught automatically.

To ensure your code follows our lint rules with:

pnpm lint                    # check the whole workspace
pnpm lint:fix                # check and auto-fix the whole workspace
pnpm lint:fix:file <file>    # check and auto-fix a single file

Pre‑commit hooks automatically lint staged files via simple-git-hooks and lint‑staged.

We use TypeScript project references for fast, incremental typechecking across the workspace:

pnpm typecheck

We use Vitest for unit testing.

pnpm test                    # all workspace tests
pnpm -F core test            # just core package
pnpm -F core test:watch      # watch core package

We use Playwright for end-to-end testing. The E2E tests live in apps/e2e/ and run against a Vite-based test app that hosts the player in multiple configurations (HTML, React, ejected skins, CDN bundles).

Playwright browsers and system dependencies are installed automatically during pnpm install. On Linux without sudo, browsers will install but system deps will be skipped with a note. If e2e tests fail due to missing system dependencies, install them manually:

sudo pnpm test:e2e:install

Running tests:

pnpm test:e2e                    # Chromium + WebKit (all engines)
pnpm test:e2e:vite               # Chromium only (fast feedback)

Visual snapshot tests verify that skin CSS and layout aren't broken. If a snapshot test fails, it means the rendered skin looks different from the baseline. This could mean:

1. You intentionally changed the skin — update the baselines:

   pnpm test:e2e:update

   Review the updated PNGs in apps/e2e/tests/visual/ to confirm they look correct, then commit them.

2. You didn't intend to change the skin — the failure caught a real regression. Inspect the diff in the Playwright HTML report:

   pnpm --dir apps/e2e report

   The report shows expected vs. actual vs. diff images side-by-side.

The sandbox (apps/sandbox/) is a Vite playground for manually exercising player changes in a browser. The root URL renders an interactive shell — a navbar with dropdowns for platform, preset, skin, styling, and source — that previews the selected combination in an iframe. One-off templates outside the main matrix are reachable by navigating directly to /<template-name>/. See apps/sandbox/templates/ for the full list.

pnpm dev:sandbox                 # sandbox + workspace package watch
pnpm dev                         # also runs the docs site

Sandbox code lives in two parallel directories:

• apps/sandbox/templates/ — source of truth, checked into git.
• apps/sandbox/src/ — your scratch copy, fully gitignored.

On pnpm dev:sandbox, setup.ts copies any file from templates/ that doesn't already exist in src/. Existing files in src/ are never overwritten, so your local changes persist across restarts.

See apps/sandbox/README.md for the full model, including the app/ shell, the @app/* alias for shared code, and how to add a new sandbox entry point.

Before opening a PR, run the workspace consistency check to catch common mistakes (CI coverage, scope mismatches, broken define imports, etc.):

pnpm check:workspace

To add a dependency to a specific package, you can use pnpm filtering from the workspace root:

pnpm -F <scope> add <package>
# Example:
pnpm -F react add @floating-ui/react-dom

To upgrade a dependency across all packages:

pnpm up <package>@<version> -r

Video.js 10 includes tooling for AI-assisted development with Claude Code. Read CLAUDE.md for repo-wide conventions, package layout, and development workflow.

Domain-specific knowledge lives in .claude/skills/. A few of the most-used skills:

See .claude/skills/README.md for the full list and workflow mappings.

When your changes introduce new patterns:

• Code conventions → Update CLAUDE.md Code Rules section
• Domain patterns → Update relevant skill in .claude/skills/

We use two types of design documents:

Design Docs (internal/design/) — Decisions you own, documented for posterity. Write one when making significant decisions in your area, choosing between approaches, or documenting architecture. See internal/design/README.md.

RFCs (rfc/) — Proposals needing buy-in from others. Write one when the decision affects multiple areas, changes shared API surface, or is hard to reverse. See rfc/README.md.

Rule of thumb: If you need someone else's approval, it's an RFC. If you're documenting your own decision, it's a Design Doc.

Skip both for: Bug fixes, small contained features, implementation details.

By submitting a pull request, you agree that your contribution is provided under the Apache 2.0 License and may be included in future releases. No contributor license agreement (CLA) has ever been required for contributions to Video.js. See the Developer's Certificate of Origin 1.1.

Whether you're adding something new, making something better, or fixing a bug, you'll first want to search the GitHub issues to make sure you're aware of any previous discussion or work. If an unclaimed issue exists, claim it via a comment. If no issue exists for your change, submit a new issue.

Before starting work, you want to update your local repository to have all the latest changes from upstream/main.

git fetch upstream
git checkout main
git pull upstream main

You want to do your work in a separate branch. In general, you want to make sure the branch is based off of the latest in upstream/main.

git checkout -b my-branch

One helpful naming convention approximates conventional commits, e.g.:

• fix/some-issue
• feat/my-media-store-feature
• docs/site-docs-for-x
• chore/repo-cleanup-task

We follow conventional commits semantics to enable automated releases.

Examples:

• feat(core): add volume smoothing hook
• fix(react): correct prop mapping for picture-in-picture
• chore(root): update linting

Any code change should come with corresponding test changes. Especially bug fixes. Tests attached to bug fixes should fail before the change and succeed with it.

pnpm test

See Testing for more information.

If your changes introduced new patterns or conventions, check if documentation needs updates:

• Site docs — User-facing documentation in site/
• AI docs — See Maintaining AI Docs

When ready, push your branch up to your fork (or upstream if you are a core contributor):

git push --set-upstream origin fix/my-issue

Then, open a PR via the green “Compare & Pull Request” button. In the description, make sure you thoroughly describe your changes and link related issues or discussions.

• Keep PRs focused and small when possible.
• Give reviewers time to provide feedback.
• Even if a PR isn’t merged, your work helps shape the direction of Video.js 10 ❤️

By making a contribution to this project, I certify that:

• (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

• (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

• (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

• (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

To discuss larger ideas or prototypes, or to help out with ongoing discussions, open a thread in:

• Discord
• GitHub Discussions