@storyblok/js

@storyblok/js is the official development kit for JavaScript applications. It provides essential functionalities:

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

Tip

Storyblok provides SDKs for React, Astro, Vue, Nuxt, and Svelte. These packages are all built on top of @storyblok/js. For other JavaScript frameworks, such as Angular or Eleventy, use @storyblok/js directly.

Requirements

• Node.js LTS (version 22.x recommended)
• Modern web browser (the latest versions of Chrome, Edge, Firefox, Safari, etc.)

Note

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:

npm install @storyblok/js@latest

Usage

Example

The following example uses the package to fetch content from the Content Delivery API, interact with the Storyblok Bridge, and link components 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 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 @storyblok/preview-bridge reference.	boolean
use	An array of plugins. Use the provided apiPlugin unless you have a custom implementation.	array
bridgeUrl	The URL of the script that initializes the Storyblok Bridge. Defaults to https://app.storyblok.com/f/storyblok-v2-latest.js.	string
richText	Deprecated and will be removed in a future version. Options for rich text rendering.	object

During initialization, storyblokInit() invokes all plugins defined in use and returns an object that merges the objects returned from each plugin. It also loads Storyblok Bridge (if enabled).

Note

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

The region parameter

Use the region key in the apiOptions object to match the space’s server location.

The following options are available:

Value	Description
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

Learn more in the spaces manual and find the region-specific base URLs in the Content Delivery API documentation.

import { apiPlugin, storyblokInit } from "@storyblok/js";
const { storyblokApi } = storyblokInit({
  accessToken: "YOUR_ACCESS_TOKEN",
  use: [apiPlugin],
  apiOptions: {
    region: "us",
  },
});

Caution

The region parameter is required for non-EU spaces.

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 the use option of storyblokInit():

storyblokInit({
  use: [apiPlugin],
});

useStoryblokBridge

useStoryblokBridge() activates the Storyblok Bridge.

useStoryblokBridge(STORY_ID, CALLBACK, BRIDGE_OPTIONS);

Learn more about the optional parameters in the @storyblok/preview-bridge reference.

registerStoryblokBridge

Alias of useStoryblokBridge().

storyblokEditable

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

storyblokEditable(blok);

To define an HTML element as editable in the Visual Editor, add both key/value pairs as attributes:

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

Learn more in the @storyblok/richtext reference.