Peer Dependencies

The @ntxmjs/react-custom-video-player relies on several external libraries to deliver its full range of features. These dependencies are classified as "peer dependencies," meaning they must be installed separately alongside the video player package. Understanding what each dependency does and why it's required will help you better manage your project and troubleshoot any issues that arise.

What Are Peer Dependencies?

Peer dependencies are packages that a library expects to be present in your project but doesn't bundle directly. This approach offers several advantages. It prevents duplicate installations of commonly used packages like React, ensures version compatibility across your entire application, and gives you control over which specific versions you want to use.

When you install @ntxmjs/react-custom-video-player, npm or yarn will notify you if peer dependencies are missing. You must install these dependencies manually to ensure the video player works correctly.

Required Dependencies

The video player requires three peer dependencies, each serving a specific and critical role in the player's functionality.

React

Package: react

Minimum Version: 18.0.0

Purpose: React is the foundational framework that powers the video player's component architecture and user interface. The player is built as a React component, utilizing React's hooks system for state management, lifecycle methods, and rendering logic.

The video player specifically requires React 18 or higher because it leverages modern features introduced in recent React versions, including concurrent rendering capabilities, improved event handling, and enhanced performance optimizations. These features enable the smooth, responsive user experience that the player delivers.

Installation:

npm install react

Why This Version?: React 18 introduced automatic batching, transitions, and suspense enhancements that improve the player's performance, particularly when handling state updates during video playback, seeking, and control interactions. Using an older version of React would result in compatibility issues and potentially degraded performance.

React DOM

Package: react-dom

Minimum Version: 18.0.0

Purpose: React DOM serves as the bridge between React components and the browser's Document Object Model. It's responsible for rendering the video player's user interface elements to the actual web page and managing all interactions with the browser environment.

The video player uses React DOM for mounting the component into your application, handling DOM events such as clicks, touches, and keyboard inputs, managing focus states for accessibility, and updating the visual interface in response to playback changes. Without React DOM, the player's React components would have no way to appear on screen or respond to user interactions.

Installation:

npm install react-dom

Why This Version?: React DOM 18 must match your React version to ensure compatibility. The version 18 release includes critical improvements to event handling and rendering behavior that the video player depends on for smooth operation across different browsers and devices.

HLS.js

Package: hls.js

Minimum Version: 1.4.0

Purpose: HLS.js is a specialized JavaScript library that enables HTTP Live Streaming support in browsers. This library is essential for one of the video player's most powerful features: the ability to play HLS streams with adaptive bitrate streaming.

HLS stands for HTTP Live Streaming, a protocol developed by Apple that delivers video content over HTTP. The protocol breaks video files into small segments and provides multiple quality levels for each segment. HLS.js implements the entire HLS protocol in JavaScript, allowing the video player to load and play .m3u8 playlist files, automatically switch between quality levels based on network conditions, buffer video segments efficiently for smooth playback, and handle various HLS features like audio tracks and subtitles.

When you provide an HLS stream URL ending in .m3u8 to the video player, HLS.js handles all the complex work of fetching the manifest file, parsing available quality levels, downloading video segments in the optimal quality, and seamlessly switching qualities as network conditions change.

Installation:

npm install hls.js

Why This Version?: Version 1.4.0 and above includes critical bug fixes, improved performance for adaptive streaming, better error handling and recovery mechanisms, and enhanced support for various HLS features. The video player is tested and optimized to work with this version range.

Installing All Peer Dependencies

For convenience, you can install all peer dependencies in a single command:

npm install react react-dom hls.js

This command installs all three required packages at once, ensuring your project has everything needed to run the video player.

Version Compatibility

The video player has been tested with specific version ranges to ensure reliable operation. Here are the recommended versions:

Verifying Dependencies

After installation, verify that all dependencies are correctly installed and at compatible versions. Check your package.json file, which should contain entries like this:

{
  "dependencies": {
    "@ntxmjs/react-custom-video-player": "^0.1.6",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "hls.js": "^1.4.0"
  }
}

The caret symbol ^ before version numbers indicates that npm will install the specified version or any newer compatible version. This is the recommended approach for staying up to date with bug fixes and minor improvements.

Understanding Without HLS.js

You might wonder: "What happens if I don't install HLS.js?" The answer depends on your use case.

If you only plan to play standard video formats like MP4, WebM, or OGG using direct URLs, the video player will function without HLS.js. These formats are natively supported by browsers and don't require additional libraries. However, if you attempt to play an HLS stream without HLS.js installed, the player will fail to load the video and may display an error.

Troubleshooting Peer Dependency Issues

If you encounter issues related to peer dependencies, here are common problems and their solutions:

Missing Peer Dependency Warning: When you install the video player, npm may display warnings about missing peer dependencies. Don't ignore these warnings. Install the missing packages immediately using the commands provided earlier in this guide.

Version Conflicts: If npm reports version conflicts, it means another package in your project requires a different version of React, React DOM, or HLS.js. In most cases, you can resolve this by updating all packages to their latest compatible versions. Run npm update to attempt automatic resolution, or manually adjust versions in your package.json file.

Module Not Found Errors: If you see errors like "Cannot find module 'hls.js'" at runtime, even after installation, try these steps:

1. Delete your node_modules folder
2. Delete your package lock file (package-lock.json, yarn.lock, or pnpm-lock.yaml)
3. Run npm install again to reinstall all dependencies
4. Restart your development server

Build Failures: If your project fails to build after adding the video player, ensure that your build tools and bundler are configured to handle React and external dependencies correctly. Most modern React setups handle this automatically, but custom configurations may need adjustment.

Next Steps

With peer dependencies installed and verified, you're ready to move forward:

• Explore the Quick Start guide to create your first video player instance
• Learn about Props configuration to customize player behavior
• Discover Icons Configuration to personalize the player's appearance

Understanding peer dependencies ensures a solid foundation for working with the video player. These libraries work together seamlessly to deliver a powerful, feature-rich video playback experience in your React application.