@storyblok/js

@storyblok/js is the JavaScript SDK for Storyblok. It enables you to perform three categories of tasks:

Fetch content from the Content Delivery API
Setup the Storyblok Bridge
Connect your frontend components with the Visual Editor

Most of the time, one of Storyblok’s frontend SDKs, such as React or Astro, should be used in projects. This SDK serves as their core dependency and is intended for direct use only when a specific SDK for the framework is unavailable or when working with plain JavaScript.

Requirements

Node.js 18+
Modern browsers

This SDK uses the Fetch API under the hood. If your environment doesn't support it, install a polyfill like isomorphic-fetch. For more information, refer to the storyblok-js-client documentation.

Installation

npm install @storyblok/js

Example

Here’s an example comprising of the package's functionalities: fetching content from the Content Delivery API, interacting with the Storyblok Bridge, and linking components on your page with the Visual Editor.

import { storyblokInit, apiPlugin, useStoryblokBridge } from '@storyblok/js'

const { storyblokApi } = storyblokInit({
  accessToken: 'YOUR_ACCESS_TOKEN',
  use: [apiPlugin],
})

// Fetch content
const { data } = await storyblokApi.get('cdn/stories', { version: 'draft' })

// Interact with the Storyblok Bridge
const story = data ? data.story : null
useStoryblokBridge(story.id, (story) => (state.story = story))

// Link your components to Storyblok Visual Editor
function init(blok) {
  const editableOptions = storyblokEditable(blok)
  const el = `<div 
    data-blok-c="${editableOptions['data-blok-c']}" 
    data-blok-uid="${editableOptions['data-blok-uid']}" 
    class="storyblok__outline">
   <!-- Content -->
  </div>`
  return el
}
// Usage
const blok = {} // your blok data received from the Storyblok API
const elementHTML = init(blok)
document.querySelector('.parent-element').innerHTML = elementHTML

Usage

`storyblokInit()`

storyblokInit(options)

storyblokInit() initializes the Storyblok SDK. storyblokInit() accepts an options object with the following keys:

Option	Description
bridge (boolean)	Whether the bridge should be initialized. (defaults to true)
accessToken (string)	The access token for the space.
use (array)	An array of plugins. Use the provided apiPlugin unless you have a custom implementation.
apiOptions (object)	Options to be passed to apiPlugin. apiOptions is imported from storyblok-js-client. For more information, see the storyblok-js-client reference.
richText (object)	Options for rich text rendering. richText is deprecated and will be removed in a future version.
bridgeUrl (string)	A URL for a script to initialize the Storyblok Bridge (defaults to https://app.storyblok.com/f/storyblok-v2-latest.js).

During initialization, storyblokInit() performs the following core functions:

Invokes all of the plugins defined in use and returns an object that merges the objects returned from each plugin
Loads the Storyblok Bridge

If you want to use the inbuilt API implementation, pass apiPlugin as an argument to use in storyblokInit(). storyblokInit() will then return storyblokApi, which is an instance of the storyblok-js-client package.

`apiPlugin()`

apiPlugin(options)

apiPlugin() provides logic that storyblokInit() can use to generate a full-featured client for the Storyblok Content Delivery API. storyblokInit() will accept apiPlugin as an item in the array passed to storyblokInit()'s use option:

storyblokInit({
  use: [apiPlugin],
})

`useStoryblokBridge()`

useStoryblokBridge(storyId, callback, options)

useStoryblokBridge() is used to subscribe to story updates.

Parameter	Description
storyId (number)	The ID of the story to subscribe to.
callback (function)	A function that will run every time a change event is triggered from the Visual Editor. The function will receive the updated story as its first and only parameter.
options (object)	Options for the Storyblok Bridge.

`registerStoryblokBridge()`

Alias of useStoryblokBridge .

`richTextResolver()`

All functionalities related to rendering rich text content have been moved to the @storyblok/richtext package.

`storyblokEditable()`

storyblokEditable(blok)

storyblokEditable() accepts a blok object (retrieved from the Content Delivery API) and returns blockEditableData , which is an object with two properties: data-blok-c and data-blok-uid.

When the key and value are added to an HTML element as an attribute, they mark the elements as editable by the Storyblok Visual Editor.

const blockEditableData = storyblokEditable(blok)
const element = `<div 
    data-blok-c="${blockEditableData['data-blok-c']}" 
    data-blok-uid="${blockEditableData['data-blok-uid']}" 
    class="storyblok__outline">
    <!-- Content -->
  </div>`