Skip to content

Install from npm#

Use the npm package when a bundler, such as webpack or Vite, builds your application's JavaScript. The package is @getstoryteller/storyteller-sdk-javascript.

Install the package#

npm install @getstoryteller/storyteller-sdk-javascript

TypeScript declarations#

The package includes TypeScript declarations. They import types from React and React Router, so the package declares these peer dependencies:

  • @types/react >=17 <20
  • @types/react-router-dom ^5.1.7

npm 7 and later installs peer dependencies for you. If npm install reports a peer dependency conflict, use an @types/react version in that range. The API reference lists the exported types.

Import the SDK and styles#

Import both files from code that runs in the browser.

import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';
import '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';

The stylesheet ships in the npm package. Configure your bundler to handle CSS imports.

Import only these two paths: the package root and @getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css. Version 11 no longer ships index.js, types/*.d.ts, or SDK source files, so other paths fail.

A default import (import Storyteller from '@getstoryteller/storyteller-sdk-javascript') works only in ES module builds. In CommonJS builds, including Jest, use import * as Storyteller.

The npm package includes the Story player, Clips player, Poll, Quiz, and caption code in its single JavaScript file. Your bundler decides how that code loads. The script-tag build downloads the same code on demand instead.

CommonJS browser bundles#

The package also supports require in browser code built with CommonJS:

const Storyteller = require('@getstoryteller/storyteller-sdk-javascript');
require('@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css');

Your bundler needs a CSS loader for the stylesheet require. Node.js can require or import the JavaScript entry, for example during server rendering, but views work only in the browser. Load the stylesheet only through your browser build.

The Storyteller Web Showcase keeps its PackagedStoryteller import and stylesheet import in one browser-only module.

Initialize the SDK#

await Storyteller.sharedInstance.initialize('demo-api-key');

Call initialize and wait for it to resolve before you create a Storyteller view. Replace demo-api-key with your API key. Top-level await works only in ES modules. Otherwise, call initialize inside an async function, as shown in Handle initialization errors.

Add a Story row#

<div id="storyteller-stories-row" style="height: 200px"></div>

const storyRow = new Storyteller.StorytellerStoriesRowView(
  'storyteller-stories-row'
);

Call storyRow.destroy() before your application removes or replaces the container.

Next steps#