@mba-web-stories/sdk

React SDK for embedding interactive web stories with video content.

Installation

npm install @mba-web-stories/sdk

Usage Options

Option 1: Standard Usage (Recommended)

For most modern build systems (Next.js, Vite, Create React App with proper configuration):

import { WebStories } from '@mba-web-stories/sdk'
// CSS will be handled by your build system
import '@mba-web-stories/sdk/styles'

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <WebStories
        galleryId="your-gallery-id"
        apiKey="your-api-key"
        config={{
          apiUrl: 'https://your-api.com/graphql',
          autoplay: false,
          showProgress: true,
          allowKeyboard: true
        }}
      />
    </div>
  )
}

Option 2: Self-Contained (Maximum Compatibility)

For environments where CSS imports might not work:

// This version has CSS inlined in JavaScript
import { WebStories } from '@mba-web-stories/sdk/inline'

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <WebStories
        galleryId="your-gallery-id"
        apiKey="your-api-key"
        config={{
          apiUrl: 'https://your-api.com/graphql'
        }}
      />
    </div>
  )
}

Option 3: Manual CSS Import

For custom setups or when you need full control:

import { WebStories } from '@mba-web-stories/sdk'
// Manually import CSS in your HTML or build process
// <link rel="stylesheet" href="node_modules/@mba-web-stories/sdk/dist/index.css">

function App() {
  return (
    <WebStories
      galleryId="your-gallery-id"
      apiKey="your-api-key"
    />
  )
}

Build System Configuration

Next.js

Add to your next.config.js:

const nextConfig = {
  transpilePackages: ['@mba-web-stories/sdk']
}

Vite

Usually works out of the box. If CSS imports fail, use the /inline version.

Webpack

Ensure CSS loading is configured:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
}

API Reference

WebStories Props

• galleryId (string, required): The ID of the gallery to display
• apiKey (string, required): Your API key for authentication
• config (object, optional): Configuration options
• className (string, optional): Additional CSS class names

Config Options

• apiUrl (string): GraphQL API endpoint
• autoplay (boolean): Auto-play videos when opened
• showProgress (boolean): Show progress bars
• allowKeyboard (boolean): Enable keyboard navigation
• muted (boolean): Start videos muted
• customStyles (object): Custom CSS styles
• onStoryChange (function): Callback when story changes
• onStoryComplete (function): Callback when story completes
• onGalleryComplete (function): Callback when gallery ends

Defensive Styling

This SDK uses aggressive defensive CSS to ensure it works in any environment:

• ✅ Scoped styles - Won't interfere with your app's CSS
• ✅ CSS reset - Immune to external CSS interference
• ✅ High specificity - Styles always apply correctly
• ✅ Runtime injection - CSS loads even if build system fails
• ✅ Multiple build targets - Works with any bundler

Troubleshooting

Styles Not Loading

1. Try the /inline import version
2. Check that your build system processes CSS imports
3. Manually import the CSS file
4. The SDK will inject fallback styles automatically

Build Errors

• Ensure your bundler supports CSS imports
• Add the package to transpilePackages in Next.js
• Use the /inline version for problematic environments

TypeScript Issues

Types are included automatically. If you have issues:

import type { WebStoriesProps } from '@mba-web-stories/sdk'