vidsphere

The official React component library for VidSphere. Seamlessly embed your VidSphere-hosted YouTube videos with a beautiful, custom, ad-free player interface.

Features

• Custom UI: A completely custom, responsive player interface built on top of the YouTube IFrame API.
• Privacy-First: Automatically uses youtube-nocookie.com to prevent tracking and bypass strict adblockers.
• Optimized Bundle: Built with tsup for extremely small, tree-shakeable ESM and CJS bundles.
• Type Safe: Fully written in TypeScript with exported declaration files.

Installation

Install the package via your preferred package manager:

npm install vidsphere
# or
pnpm add vidsphere
# or
yarn add vidsphere

Note: react and react-dom (v18+) are required peer dependencies.

Quick Start

1. Global Configuration

Before rendering the player, you should configure the library with your VidSphere backend URL. The best place to do this is at the entry point of your application (e.g., main.tsx, App.tsx, or _app.tsx).

import { VidSphere } from 'vidsphere';

VidSphere.config({
  baseUrl: 'https://your-backend.com', // e.g., your VidSphere API endpoint
  // apiKey: 'optional-api-key'
});

2. Using the Player Component

Once configured, use the YouTubePlayer component anywhere in your app. Pass the database id of your uploaded video as a prop.

The player will automatically fetch the necessary metadata (like the YouTube Video ID and thumbnail) from your VidSphere backend and render the custom video player.

import { YouTubePlayer } from 'vidsphere';

function MyVideoPage() {
  return (
    <div style={{ maxWidth: '800px', margin: '0 auto' }}>
      <h1>Check out this video!</h1>
      
      <YouTubePlayer 
        id="6c4c2aef-7d9a-4659-b186-786f4b913ef2" 
        style={{ width: '100%', aspectRatio: '16/9', borderRadius: '12px' }} 
      />
    </div>
  );
}

export default MyVideoPage;

Props API

YouTubePlayer

| Prop | Type | Required | Description | | :--- | :--- | :--- | :--- | | id | string | Yes | The unique ID of the video record from your VidSphere database. | | className | string | No | Optional CSS classes to apply to the player wrapper. | | style | React.CSSProperties | No | Optional inline styles to apply to the player wrapper. |

VidSphere.config()

| Option | Type | Required | Description | | :--- | :--- | :--- | :--- | | baseUrl | string | Yes | The URL of your backend handling the VidSphere API requests. | | apiKey | string | No | Optional API key to authenticate metadata requests if your endpoint requires it. |

License

MIT