Skip to main content

Announcing @storyblok/js

Developers Alex Jover Morales Alex Jover Morales
Back to all posts
Announcing @storyblok/js

Storyblok editing capabilities

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

Developer Newsletter

Want to stay on top of the latest news and updates in Storyblok?
Subscribe to Code & Bloks - our headless newsletter.

An error occurred. Please get in touch with marketing@storyblok.com

Please select at least one option.

Please enter a valid email address.

This email address is already registered.

Please Check Your Email!

Almost there! To confirm your subscription, please click on the link in the email we’ve just sent you. If you didn’t receive the email check your ’junk folder’ or


More to read