🍪 Cookie Notice

We use cookies to learn how you interact with our content, and show you relevant content and ads based on your browsing history. You can adjust your settings below. Here's our policy.

Cookie settings
Skip to main content

Announcing @storyblok/js

Developers
Alex Jover Morales
Try for Free

Storyblok is the first headless CMS that works for developers & marketers alike.

We're more than excited to show you @storyblok/js: our latest piece of work that allows you to integrate Storyblok with any JavaScript framework in 3 simple steps.

But it wasn't always like that. If you've used Storyblok before with React or Vue, for instance, you needed to add multiple packages (like storyblok-js-client and storyblok-bridge) and configured them manually to fully connect Storyblok with your website.

Not anymore! @storyblok/js is written with DX in mind and we carefully thought about how to make it as easy as possible for you to connect Storyblok with Svelte, Remix, Astro, or any other JavaScript framework that we don't have an official SDK for.

Let's see how you can use it right away!
(Huge kudos to Facundo and Arisa for their hard work on this 👏)

Usage

Start by installing @storyblok/js:

npm install @storyblok/js
#yarn add @storyblok/js

In the entry point of your app (usually main.js), initialize it:

main.js 
import { storyblokInit, apiPlugin } from "@storyblok/js";

const { storyblokApi } = storyblokInit({
  accessToken: "<your-token>",
  use: [apiPlugin],
});

That will initialize storyblokApi and load Storyblok Bridge in the background. You can also set apiOptions and conditionally load the bridge:

With apiOptions and conditionally loading the bridge 
const { storyblokApi } = storyblokInit({
  accessToken: "<your-token>",
  bridge: process.env.NODE_ENV !== "production",
  apiOptions: { /* storyblok-js-client options */ }
  use: [apiPlugin],
});

Querying Storyblok API

You can use the returned storyblokApi. It's actually an instance of storyblok-js-client so all its methods will work:

Fetching content 
const { data } = await storyblokApi.get("cdn/stories/home", {
  version: "draft"
})
const story = data.story

Listening for changes of Storyblok Visual Editor

First, you need to connect Storyblok Bridge with the Visual Editor. You can use a useStoryblokBridge function we provide you:

Connect Bridge with Visual Editor 
import { useStoryblokBridge } from "@storyblok/js";

useStoryblokBridge(story.id, (newStory) => (story = newStory));

Lastly, you need to link your app and Storyblok components together. That depends on the framework but, in the end, you must add the data-blok-c and data-blok-uid attributes, and the storyblok__outline class.

We provide you a storyblokEditable function to make that easier. As an example, you can check in @storyblok/vue how we use a v-editable directive for that:

v-editable example 
import { storyblokEditable } from "@storyblok/js";

const vEditableDirective = {
  bind(el, binding) {
    if (binding.value) {
      const options = storyblokEditable(binding.value);
      el.setAttribute("data-blok-c", options["data-blok-c"]);
      el.setAttribute("data-blok-uid", options["data-blok-uid"]);
      el.classList.add("storyblok__outline");
    }
  },
};

At this point, you'll have your app connected to Storyblok with the real-time editing experience fully enabled 🚀

Feel free to check out @storyblok/js docs for more details.

Next steps

In the coming days/weeks we'll release:

We believe the future of Storyblok SDKs is looking great! What do you think? 😉

ResourceLink
@storyblok/js docshttps://github.com/storyblok/storyblok-js
Storyblok Learning Hubhttps://www.storyblok.com/docs

More to read