Announcing @storyblok/js

Developers January 25, 2022

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

We're more than excited to show you @storyblok/js (opens in a new window) : 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 (opens in a new window) and storyblok-bridge (opens in a new window) ) 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 (opens in a new window) , Remix (opens in a new window) , Astro (opens in a new window) , 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 (opens in a new window) and Arisa (opens in a new window) 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 (opens in a new window) 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 (opens in a new window) 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 (opens in a new window) for more details.

Next steps

In the coming days/weeks we'll release:

Refactored SDKs: @storyblok/vue (opens in a new window) , @storyblok/nuxt (opens in a new window) , gatsby-source-storyblok (opens in a new window) (they'll have the same 3-steps DX ⚡️)
Brand new SDKs: @storyblok/react, (maybe?) @storyblok/svelte
Articles with live demos on how to connect Storyblok with some of the newest frameworks

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

Resource	Link
@storyblok/js docs	https://github.com/storyblok/storyblok-js
Storyblok Learning Hub	https://www.storyblok.com/docs