NPO React Player

A React wrapper for the @npo/player library.

Getting Started

1. Install the package
2. Sign a JWT according to the @npo/player documentation
3. Import the NpoPlayer component
4. Add the component to your application

// npm
npm install @npo/react-player

// yarn
yarn add @npo/react-player

import { NpoPlayer } from '@npo/react-player'

export const MyPlayer = () => {
  const { data, isSuccess } = useMyPlayerToken()

  return <NpoPlayer isEnabled={isSuccess} jwt={data?.token} />
}

Next.js

The NPO React Player package is importing the stylesheet from the @npo/player libray. To be able to use this import from an NPM module, you need to to add the NPO React Player to the transpilePackages in the next.config.js.

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@npo/react-player']
}

module.exports = nextConfig

NPO Tag

The NPO React Player package has a dependency on the NPO Tag SDK. This SDK is a private repository. You will need to define an auth token and a registry server to be able to install this dependency.

Available properties

children

You can add children to the NpoPlayer component. The children will be displayed on top of the Player instance.

export const MyPlayer = () => {
  const { data, isError, isLoading } = useMyPlayerToken()

  return (
    <NpoPlayer isEnabled={!isLoading} jwt={data?.token}>
      {isLoading && <MyPlayerLoader />}

      {isError && <MyPlayerError />}
    </NpoPlayer>
  )
}

className

You can add class names as property to the NpoPlayer component to style your player implementation.

export const MyPlayer = () => {
  return <NpoPlayer className='aspect-h-9 aspect-w-16' />
}

handleError

You can add a handleError event handler as property to the NpoPlayer component. This handler returns a statusCode value on which you can customize your error handling.

export const MyPlayer = () => {
  const [showRestrictionError, setShowRestrictionError] = React.useState<boolean>(false)

  const handleError = React.useCallback((statusCode: number) => {
    setShowRestrictionError(statusCode === 450)
  }, [])

  return (
    <NpoPlayer handleError={handleError}>
      {showRestrictionError && <MyRestrictionError />}
    </NpoPlayer>
}

isEnabled

You can add an isEnabled boolean as property to the NpoPlayer component for any dependency that needs to be resolved before the initialization of the player instance.

export const MyPlayer = () => {
  const { isLoadingA } = useMyPlayerDepA()
  const { isLoadingB } = useMyPlayerDepB()

  return <NpoPlayer isEnabled={!isLoadingA && !isLoadingB} />
}

jwt

You have to add the JWT as property to the NpoPlayer component. The JWT is the only required property for the player to play.

export const MyPlayer = () => {
  const { data, isSuccess } = useMyPlayerToken()

  return <NpoPlayer isEnabled={isSuccess} jwt={data?.token} />
}

npoTagInstance

You can add the NPO Tag instance as property to the NpoPlayer component.

import { npoTagInstance } from './npoTag.service.ts'

export const MyPlayer = () => {
  return <NpoPlayer npoTagInstance={npoTagInstance} />
}

npoTagPageTracker

You can add the NPO Tag pageTracker as property to the NpoPlayer component.

import { npoTagPageTracker } from './npoTag.service.ts'

export const MyPlayer = () => {
  return <NpoPlayer npoTagPageTracker={npoTagPageTracker} />
}

playerConfig

You can add a player configuration as property to the NpoPlayer component. The available configuration options can be found in the @npo/player documentation.

export const MyPlayer = () => {
  return <NpoPlayer playerConfig={{ cast: { enable: false } }} />
}

streamOptions

You can add stream options as property to the NpoPlayer component. See all available options in the @npo/player documentation.

export const MyPlayer = () => {
  return <NpoPlayer streamOptions={{ autoplay: true, liveOffset: false, startOffset: 60 }} />
}

Environment variables

You can define three environment variables to run the player. If you define these environment variables, you don't have to add these values to the playerConfig and the streamOptions properties: these will be applied as the default values.

NPO_PLAYER_ANALYTICS_KEY=
NPO_PLAYER_LICENSE_KEY=
NPO_PLAYER_URL=

Next.js

When you are using Next.js you will have to prefix the environment variables with the NEXT_PUBLIC_ prefix for the variables to be available in the browser environment.

Releases

This package is released automatically with semantic-release on every push to main.

Example workflow

1. Make your changes
2. Use a Conventional Commit style pull request title (for example: feat:, fix:, chore:)
3. Open and merge a pull request into main
4. GitHub Actions runs semantic-release on main, publishes the package, and creates or updates the GitHub Release automatically

GitHub Release content

• Release name is the semantic-release tag (e.g. 2.3.1).
• Release body is set to the merged pull request title (for the exact merge commit that triggered the workflow).
• Strict mode: the workflow fails when no exact merged PR matches the current commit.
• Strict mode: the workflow fails when more than one semantic-version tag points at the current commit.
• If no semantic-release tag exists on the current main commit, GitHub Release publishing is skipped.

One-time npm setup (Trusted Publishing)

The release workflow uses npm Trusted Publishing, so no long-lived npm token is required.

1. Open npm package settings for @npo/react-player.
2. Add a Trusted Publisher for GitHub Actions.
3. Configure it for repository Nederlandse-Publieke-Omroep/npo-start-web-player.
4. Select workflow file release.yml.

Note: The release workflow intentionally does not use dependency caching, in line with npm Trusted Publishing guidelines for release builds.