@storyblok/js

@storyblok/js is Storyblok’s official development kit for JavaScript applications. It provides three main functionalities:

Fetch content from the Content Delivery API
Set up the Storyblok Bridge
Connect frontend components with the Visual Editor
Render rich text content

Real-world projects are usually built using JavaScript frameworks. Storyblok provides dedicated SDKs for React, Astro, Vue, Nuxt, and Svelte. @storyblok/js 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 LTS (version 22.x recommended)
Modern web browser (e.g., Chrome, Firefox, Safari, Edge – latest versions)

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

Add the package to a project by running this command in the terminal:

npm install @storyblok/js@latest

Usage

Example

A complete example illustrating 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',
	apiOptions: {
		region: 'eu',
	},
	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 components to the 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;
}
// Render components
const blok = {}; // Block object received from the Content Delivery API
const elementHTML = init(blok);
document.querySelector('.parent-element').innerHTML = elementHTML;

API

`storyblokInit`

storyblokInit() initializes the Storyblok SDK.

storyblokInit(options)

storyblokInit() accepts an options object with the following keys:

Key	Description	Type
`accessToken`	The access token for the space. Learn more in the access tokens concept.	string
`apiOptions`	API options are passed to the `Storyblok` class in storyblok-js-client.	object
`bridge`	Enable or disable the Storyblok Bridge. Enabled by default. Learn more in the Visual Editor concept and the StoryblokBridge reference.	boolean
`use`	An array of plugins. Use the provided `apiPlugin` unless you have a custom implementation.	array
`richText`	Options for rich text rendering. `richText` is deprecated and will be removed in a future version.	object
`bridgeUrl`	The URL for a script to initialize the Storyblok Bridge. Defaults to `https://app.storyblok.com/f/storyblok-v2-latest.js`.	string

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

Invoke all plugins defined in use and return an object that merges the objects returned from each plugin
Loads Storyblok Bridge (if enabled)

To use the inbuilt API implementation, pass apiPlugin as an argument to use in storyblokInit(). storyblokInit() returns storyblokApi, which is an instance of the storyblok-js-client package. See the storyblok-js-client package reference for further information.

Example: Region parameter

Use the region key in the apiOptions object to match the server location of the space. Learn more in the spaces concept and find an overview of region-specific base URLs in the Content Delivery API documentation. The following options are available:

`eu`	For spaces created in the EU. Default.
`us`	For spaces created in the US.
`ap`	For spaces created in Australia.
`ca`	For spaces created in Canada.
`cn`	For spaces created in China.

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

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

The region parameter must be specified unless the space was created in the EU.

`apiPlugin`

apiPlugin() provides logic that storyblokInit() uses to generate a full-featured client for the Storyblok Content Delivery API.

apiPlugin(OPTIONS)

storyblokInit() accepts apiPlugin as an item in the array passed to storyblokInit()'s use option:

storyblokInit({
  use: [apiPlugin],
})

`useStoryblokBridge`

useStoryblokBridge() activates the Storyblok Bridge.

useStoryblokBridge(STORY_ID, CALLBACK, BRIDGE_OPTIONS)

For the BRIDGE_OPTIONS, see the StoryblokBridge reference.

`registerStoryblokBridge`

Alias of useStoryblokBridge() .

`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 element 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>`;

`richTextResolver`

Check our official @storyblok/richtext package. All functionalities related to rendering rich text are included with this package.