@flowplayer/spins

@flowplayer/spins

A TypeScript library for creating Flowplayer playlist components optimized for short-form video content like Reels and Shorts.

import { createSpins } from "@flowplayer/spins";

const spinsContainer = createSpins({ 
  playlist: "your-playlist-id",
  token: "your-token",
  lang: "en",
});
document.body.appendChild(spinsContainer);

React Usage

import { createSpins, type SpinsConfig } from "@flowplayer/spins";
import { useEffect, useRef } from "react";

function SpinsPlayer({ playlistId }: { playlistId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (containerRef.current) {
      const spinsContainer = createSpins({ 
        playlist: playlistId,
        token: "your-token",
        lang: "en",
      });
      containerRef.current.appendChild(spinsContainer);
    }
  }, [playlistId]);

  return <div ref={containerRef} className="spins-container" />;
}

Features

• 🎯 Type-safe - Built with TypeScript and Zod schema validation
• 🛡️ Runtime validation - Safely deserializes API responses
• 🎨 Styled components - Includes CSS for playlist styling
• 🔧 Error handling - Graceful fallbacks for network and validation errors
• 📦 ESM ready - Modern ES modules with tree-shaking support
• 📱 Short-form optimized - Designed for vertical video content like TikTok, Instagram Reels, and YouTube Shorts

Installation

npm install @flowplayer/spins
# or
bun add @flowplayer/spins

Usage

import { spins, type SpinsConfig } from "@flowplayer/spins";

// Create a playlist component for short-form content
const config: SpinsConfig = {
  playlist: "your-playlist-id", // or array of SpinItem objects
  token: "your-flowplayer-token",
  lang: "en"
};

const spinsContainer = spins(config);
document.body.appendChild(spinsContainer);

Short-Form Video Content

This library is specifically designed to handle short-form video playlists, making it easy to create engaging vertical video experiences similar to:

• TikTok-style feeds - Vertical scrolling through short videos
• Instagram Reels - Quick, engaging video content
• YouTube Shorts - Bite-sized video experiences

The component automatically handles playlist loading and provides the structure needed for smooth, mobile-optimized video playback.

API Reference

createSpins(config: SpinsConfig): SpinsContainer

Creates a Flowplayer playlist component container optimized for short-form video content.

Parameters

• config.playlist: string | Array<SpinConfig> - The playlist ID or array of spin configurations
• config.token: string - Your Flowplayer token
• config.lang: string - Language code (e.g., "en", "es")

Returns

Returns a SpinsContainer (extends HTMLElement) with event handling capabilities:

• on(event, handler) - Subscribe to events
• off(event, handler) - Unsubscribe from events

Events

• SPIN_CREATED - Fired when a new spin is created
• SPIN_IN_VIEWPORT - Fired when a spin enters the viewport

Error Handling

The function gracefully handles:

• Network errors (API unavailable, timeout, etc.)
• Invalid playlist configurations
• HTTP errors (404, 500, etc.)

TypeScript Support

The library exports TypeScript types for full type safety:

import { type SpinsConfig, type SpinItem, type SpinsContainer } from "@flowplayer/spins";

SpinsConfig

The main configuration interface:

interface SpinsConfig {
  playlist: string | Array<SpinItem>;
  token: string;
  lang: string;
}

SpinItem

Individual spin configuration:

interface SpinItem {
  src: Config["src"];
  title?: string;
  poster?: string;
  description?: string;
  subtitles?: SubtitlesConfig["subtitles"];
}

CSS Styling

The component includes default CSS styling optimized for short-form video content. Styles are imported from: You can override styles by targeting the spins container and its children:

.spins-container {
  /* Base spins container styles */
}

flowplayer-spin {
  /* Individual spin container styles */
}

Development

Prerequisites

• Bun runtime
• TypeScript 5+

Scripts

# Development with Storybook
bun run dev

# Build the library
bun run build

# Build TypeScript declarations
bun run build:dts

# Run tests
bun run test

# Lint and format code
bun run lint

# Build Storybook for production
bun run build-storybook

Contributing

This project uses:

• Biome for linting and formatting
• Husky for pre-commit hooks
• Vitest with Playwright for browser testing
• Storybook for component development and documentation
• Lit for custom web components

License

This is a paid feature of the Wowza Flowplayer platform. Usage requires a valid Flowplayer license.