Skip to main content

Embed Streams with NPM Package

Learn how to integrate Streams directly into your website using our JavaScript/TypeScript NPM package, giving you full control over the user experience while leveraging our powerful streaming capabilities.

Overview​

The @streamscloud/embeddable package allows you to embed Streams into any website with complete customization control. Unlike our Widget system, this approach lets you:

  • Custom Stream Tiles - Design your own stream preview components
  • Brand Integration - Seamlessly match your existing website design
  • Event Control - Handle user interactions exactly how you want
  • Framework Flexibility - Works with React, Vue, Svelte, or vanilla JavaScript

How It Works​

The integration follows a simple pattern:

  1. Create Stream Tiles - Build custom components to display your streams
  2. Handle Click Events - Capture when users want to view a stream
  3. Open Stream Player - Trigger our full-screen player experience
  4. Manage Player Lifecycle - Control when the player opens and closes

Key Components​

Stream Player Modal​

The core component that provides the full-screen viewing experience:

  • Full-screen immersive viewing
  • Navigation between stream pages
  • Product integration and shopping
  • Analytics tracking
  • Mobile-optimized experience

GraphQL Client​

Required for fetching stream data and managing authentication:

  • Handles API communication
  • Manages user sessions
  • Provides real-time updates
  • Ensures data consistency

Basic Integration Flow​

import { openStreamPlayer } from '@streamscloud/embeddable/stream-player';

// 1. Open player when user clicks your custom tile
const handleStreamClick = (streamId: string) => {
  openStreamPlayer({
    streamId: streamId,
    graphqlUrl: 'https://api.streamscloud.com/graphql'
  });
};

Custom Stream Tiles​

You have complete freedom to design how streams appear on your website:

<!-- Your custom stream tile -->
<div class="stream-tile" onclick="handleStreamClick('streamId123')">
  <img src="stream-thumbnail.jpg" alt="Stream preview" />
  <h3>Stream Title</h3>
  <p>Stream description...</p>
  <button>Watch Now</button>
</div>

Framework Support​

Vanilla JavaScript​

Perfect for simple integrations or adding to existing websites without frameworks.

TypeScript​

Full type safety with comprehensive TypeScript definitions included.

Svelte​

Native support as shown in our example code, with reactive updates and component lifecycle management.

React/Vue​

Compatible with all major frameworks through standard web component patterns.

Authentication Options​

Public Streams​

For publicly accessible content, minimal configuration is required.

Benefits Over Widgets​

While Widgets are great for quick deployment, the NPM package offers:

  • Complete Design Control - No styling limitations
  • Custom Interactions - Handle events exactly as needed
  • Performance Optimization - Load only what you need
  • Advanced Integration - Deep integration with your existing codebase
  • Analytics Control - Custom tracking and measurement

The NPM package gives you the power of Streams with the flexibility to create exactly the experience your users need.