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: 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:

Refactored SDKs: @storyblok/vue, @storyblok/nuxt, gatsby-source-storyblok (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

Announcing @storyblok/js

Usage

Querying Storyblok API

Listening for changes of Storyblok Visual Editor

Next steps

More to read