player-loader-webpack-plugin

The official webpack plugin for the Brightcove Player.

Table of Contents generated with DocToc

• Installation
• Compatibility
• Basic Usage
• How it Works
  • Limitations
  • Auto Setup
  • Manual Setup via bc Function
  • Setting a Source
• Putting it All Together
• Running the Demo Project
• Options
  • prependTo
  • accountId
  • embedId
  • playerId
• More Resources

Installation

To install, use:

npm install --save-dev @brightcove/player-loader-webpack-plugin

Compatibility

This webpack plugin supports webpack 3.x & webpack 4.x

Basic Usage

First, require the plugin at the top of your webpack.config.js:

const PlayerLoader = require('@brightcove/player-loader-webpack-plugin');

Then create an instance of the PlayerLoader plugin in the plugins array:

Note: accountId is a required parameter!

plugins: [
  new PlayerLoader({accountId: '12345678910'})
]

Note: If you have more than one output, we will automatically pick the first output with a .js extension. If you want to control that see the prependTo option.

For a full list of options, see the Options section below.

How it Works

This webpack plugin will prepend your Brightcove Player to your bundle. Doing this can reduce the number of requests needed by your website and ensure that the global bc function is available synchronously.

Limitations

There are several limitations and caveats to using this plugin.

1. iframe embeds are not supported. This plugin is only suitable for use with in-page/advanced embeds.
2. If your player is updated or republished, the bundle will need to be re-generated before the bundled player is updated.

As an alternative, users who want an iframe embed or want to load their player script asynchronously can use the @brightcove/player-loader project instead, which downloads players at runtime rather than at build time. It does not have these limitations.

Auto Setup

When your bundle executes, the Player will automatically set up any embed elements that match certain criteria:

1. Must be either a <video> or <video-js> element.
2. Must have a data-player attribute that is equivalent to the playerId of the bundled player.
3. Must have a data-embed attribute that is equivalent to the embedId of the bundled player.

For example, if this project is used with the following configuration:

plugins: [
  new PlayerLoader({
    accountId: '12345678910',
    playerId: 'abc123xyz',
    embedId: 'default'
  })
]

The following embed elements will be automatically initialized when the bundle executes:

<video-js
  data-player="abc123xyz"
  data-embed="default">
</video-js>

<video
  data-player="abc123xyz"
  data-embed="default">
</video>

This behavior is implicit to the Brightcove Player, not this plugin.

Manual Setup via bc Function

Any embeds that cannot be auto set up will need to be manually set up using the global bc function (or window.bc).

This function is created by all Brightcove Players. Its signature matches the videojs function - please refer to that documentation for a complete description.

At a minimum, the bc function takes an element or id attribute value. And, just like videojs, the bc function returns a Video.js Player instance:

const player = bc(document.querySelector('video-js'));

Setting a Source

Most Video Cloud users configure sources either in the Studio application or via programmatic methods. However, using the Video.js src method works as well:

player.src({src: 'https://vjs.zencdn.net/v/oceans.mp4', type: 'video/mp4'});

Putting it All Together

This is a complete example for using this webpack plugin, which will bundle an imaginary Brightcove Player and set it up manually (as described above). It may also be beneficial to try the included demo project.

First, set up the webpack.config.js properly:

const PlayerLoader = require('@brightcove/player-loader-webpack-plugin');

module.exports = {

  // Additional configuration for entry, output, etc.

  plugins: [
    new PlayerLoader({accountId: '12345678910'})
  ]
};

Second, in the JavaScript source (somewhere in the webpack entry point or in an imported path):

// Because the player is prepended to the bundle, the global `bc` function
// will be available immediately.
//
// Note that if your bundle needs to be executed in a Node.js environment
// instead of just the browser, we advise using the something like the
// `global` package on npm.
const bc = window.bc;

// Create a video-js element (or find one in the DOM).
const playerEl = document.createElement('video-js');

// Append it to the body.
document.body.appendChild(playerEl);

// Make that element into a Brightcove Player.
const player = bc(playerEl);

// At this point, the player is created. A source can be set or any other
// integration can be written.
player.src({src: 'https://vjs.zencdn.net/v/oceans.mp4', type: 'video/mp4'});

Running the Demo Project

This project's Git repository comes with a working demo project.

1. Clone the repo: git clone https://github.com/brightcove/player-loader-webpack-plugin
2. Move into the directory: cd player-loader-webpack-plugin
3. Install dependencies: npm i
4. Set environment variables that will configure the demo. At a minimum, BC_ACCOUNT_ID: export BC_ACCOUNT_ID="1234567890" (BC_PLAYER_ID and BC_EMBED_ID are also supported).
5. Run the demo: npm run start to run the demo and a local server
6. If everything succeeds, wait for the web server to start then open http://localhost:9999/ in the browser.

Options

prependTo

• Type: string | regex | (regex|string)[]

By default we prepend the player to the first file with a .js extension that is listed as an output.

If you only want to prepend to certain file(s) you may pass a string or regex that will be used to match against webpacks output filenames array. You can optionally pass an array in prependTo, and the player will be prepended to any file that matches any item in the array (regex or string).

// Example of matching files output by webpack when code splitting
const filenames = ['bundle.js', 'bundle.1.js', 'bundle.2.js', 'playerBundle.js'];

// webpack.config.js
module.exports = {

  // ... Additional configuration for entry, output, etc.

  plugins: [
    new PlayerLoader({
      accountId: '12345678910',
      // matches bundle.js only
      // prependTo: 'bundle.js',

      // matches all files starting with bundle
      // prependTo: /^bundle/,

      // matches both bundle.js and playerBundle.js only
      // prependTo: [/^bundle\.js/, /^player/],
    })
  ]
};

accountId

• REQUIRED
• Type: string | number

A Video Cloud account ID.

embedId

• Type: string
• Default: 'default'

The Brightcove Player embed ID for the player. The default value is correct for most users.

playerId

• Type: string
• Default: 'default'

A Brightcove Player ID.

More Resources

• Brightcove Guides
• API Docs
• Video.js Guides