The JavaScript SDK you need to interact with Storyblok API and enable the Real-time Visual Editing Experience.
If you are first-time user of the Storyblok, read the Getting Started guide to get a project ready in less than 5 minutes.
Install @storyblok/js:
npm install @storyblok/js
// yarn add @storyblok/js
⚠️ This SDK uses the Fetch API under the hood. If your environment doesn't support it, you need to install a polyfill like isomorphic-fetch. More info on storyblok-js-client docs.
Install the file from the CDN:
<script src="https://unpkg.com/@storyblok/js"></script>Register the plugin on your application and add the access token of your Storyblok space. You can also add the apiPlugin in case that you want to use the Storyblok API Client:
import { storyblokInit, apiPlugin } from "@storyblok/js";
const { storyblokApi } = storyblokInit({
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
});That's it! All the features are enabled for you: the Api Client for interacting with Storyblok CDN API, and Storyblok Bridge for real-time visual editing experience.
You can enable/disable some of these features if you don't need them, so you save some KB. Please read the "Features and API" section
Possible values:
eu(default): For spaces created in the EUus: For spaces created in the USap: For spaces created in Australiaca: For spaces created in Canadacn: For spaces created in China
Full example for a space created in the US:
import { storyblokInit, apiPlugin } from "@storyblok/js";
const { storyblokApi } = storyblokInit({
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
apiOptions: {
region: "us",
},
});Note: For spaces created in the United States or China, the
regionparameter must be specified.
@storyblok/js does three actions when you initialize it:
- Provides a
storyblokApiobject in your app, which is an instance of storyblok-js-client. - Loads Storyblok Bridge for real-time visual updates.
- Provides a
storyblokEditablefunction to link editable components to the Storyblok Visual Editor.
Inject storyblokApi:
import { storyblokInit, apiPlugin } from "@storyblok/js";
const { storyblokApi } = storyblokInit({
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
});
const { data } = await storyblokApi.get("cdn/stories", { version: "draft" });Note: if you don't use
apiPlugin, you can use your prefered method or function to fetch your data.
Use useStoryblokBridge or registerStoryblokBridge to get the new story every time is triggered a change event from the Visual Editor. You need to pass the story id as first param, and a callback function as second param to update the new story:
import { storyblokInit, apiPlugin, useStoryblokBridge } from "@storyblok/js";
const { storyblokApi } = storyblokInit({
accessToken: "YOUR_ACCESS_TOKEN",
use: [apiPlugin],
});
const { data } = await storyblokApi.get("cdn/stories", { version: "draft" });
const story = data ? data.story : null;
useStoryblokBridge(story.id, (story) => (state.story = story));You can pass Bridge options as a third parameter as well:
useStoryblokBridge(story.id, (story) => (state.story = story), {
resolveRelations: ["Article.author"],
resolveLinks: "url"
});To link your app and Storyblok components together will depend on the framework you are using. 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.
You can choose the features to use when you initialize the plugin. In that way, you can improve Web Performance by optimizing your page load and save some bytes.
You can use an apiOptions object. This is passed down to the (storyblok-js-client config object](https://github.com/storyblok/storyblok-js-client#class-storyblok):
const { storyblokApi } = storyblokInit({
accessToken: "YOUR_ACCESS_TOKEN",
apiOptions: {
// storyblok-js-client config object
cache: { type: "memory" },
},
use: [apiPlugin],
});If you prefer to use your own fetch method, just remove the apiPlugin and storyblok-js-client won't be added to your application.
storyblokInit({});You can conditionally load it by using the bridge option. Very useful if you want to disable it in production:
const { storyblokApi } = storyblokInit({
bridge: process.env.NODE_ENV !== "production",
});If you don't use useStoryblokBridge or registerStoryblokBridge, you have still access to the raw window.StoryblokBridge:
const sbBridge = new window.StoryblokBridge(options);
sbBridge.on(["input", "published", "change"], (event) => {
// ...
});You can easily render rich text by using the renderRichText function that comes with @storyblok/js:
import { renderRichText } from "@storyblok/js";
const renderedRichText = renderRichText(blok.richtext);You can set a custom Schema and component resolver globally at init time by using the richText init option:
import { RichTextSchema, storyblokInit } from "@storyblok/js";
import cloneDeep from "clone-deep";
const mySchema = cloneDeep(RichTextSchema); // you can make a copy of the default RichTextSchema
// ... and edit the nodes and marks, or add your own.
// Check the base RichTextSchema source here https://github.com/storyblok/storyblok-js-client/blob/master/source/schema.js
storyblokInit({
accessToken: "<your-token>",
richText: {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
default:
return "Resolver not defined";
}
},
},
});You can also set a custom Schema and component resolver only once by passing the options as the second parameter to renderRichText function:
import { renderRichText } from "@storyblok/js";
renderRichText(blok.richTextField, {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
break;
default:
return `Component ${component} not found`;
}
},
});
- Storyblok Technology Hub: Storyblok integrates with every framework so that you are free to choose the best fit for your project. We prepared the technology hub so that you can find selected beginner tutorials, videos, boilerplates, and even cheatsheets all in one place.
- Getting Started: Get a project ready in less than 5 minutes.
- Storyblok CLI: A simple CLI for scaffolding Storyblok projects and fieldtypes.
- Bugs or Feature Requests? Submit an issue.
- Do you have questions about Storyblok or you need help? Join our Discord Community.
Please see our contributing guidelines and our code of conduct. This project use semantic-release for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check this question about it in semantic-release FAQ
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent