# Install from npm
URL: /getting-started/npm/

## Task
Install the Web SDK package, import its stylesheet, and create a Story row.

## Metadata
- Slug: getting-started-npm
- Source: public-docs/getting-started/npm.md
- Audience: Engineers using a JavaScript bundler
- Platforms: Web
- Related: Quickstart, React and Next.js, Configure Views, API Reference

## Overview
- Installs `@getstoryteller/storyteller-sdk-javascript` from npm.
- Lists the TypeScript peer dependencies: `@types/react` `>=17 <20` and `@types/react-router-dom` `^5.1.7`.
- Uses a namespace import and imports the required `dist/storyteller.min.css` export.
- Limits imports to the package root and the stylesheet path. Version 11 no longer ships `index.js`, `types/*.d.ts`, or SDK source files.
- Notes that a default import works only in ES module builds. CommonJS builds, including Jest, use `import * as Storyteller`.
- Notes that the npm file includes the player, Poll, Quiz, and caption code, and the bundler decides how it loads.
- Shows the CommonJS `require` path for browser bundles with a CSS loader. Node.js can load the entry for server rendering, but views work only in the browser.
- Initializes the SDK, creates a Story row in a container with a height, and calls `destroy()` before the host application removes the container.

## When To Use
- Use this path when the application bundles JavaScript and CSS imports.
- Use the TypeScript section when npm reports a peer dependency conflict.
- Use the CommonJS example only when the browser bundler handles the stylesheet `require`.

## API Cheat Sheet
- `Storyteller.sharedInstance.initialize(apiKey)`: Initializes the SDK.
- `new Storyteller.StorytellerStoriesRowView(containerId)`: Creates a Story row.
- `storyRow.destroy()`: Releases the view before container removal.

## Canonical Reference
# 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`](https://www.npmjs.com/package/@getstoryteller/storyteller-sdk-javascript).

## Install the package

```shell
npm install @getstoryteller/storyteller-sdk-javascript
```

### TypeScript declarations {#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](../reference/index.md#typescript-declarations) lists the
exported types.

## Import the SDK and styles

Import both files from code that runs in the browser.

```javascript
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:

```javascript
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](https://github.com/getstoryteller/storyteller-showcase-web/blob/11.0.0/nextjs/src/components/contexts/loadPackagedStoryteller.ts#L1)
and stylesheet import in one browser-only module.

## Initialize the SDK

```javascript
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](../Quickstart.md#handle-initialization-errors).

## Add a Story row

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

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

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

## Next steps

- [Show your first Story row](../Quickstart.md)
- [Use React or Next.js](react-nextjs.md)
- [Configure views](../StorytellerListView.md)