Announcing @storyblok/js

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:

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:

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:

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:

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:

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? 😉