@storyblok/vue
The Vue SDK you need to interact with Storyblok API and enable the Real-time Visual Editing Experience.
Note: This plugin is for Vue 3. Check out the docs for Vue 2 version.
🚀 Usage
Check out the Live Demo on Stackblitz!
If you are first-time user of the Storyblok, read the Getting Started guide to get a project ready in less than 5 minutes.
Installation
Install @storyblok/vue
npm install @storyblok/vue
# yarn add @storyblok/vue
Register the plugin on your application (usually in main.js
), add the apiPlugin
and add the access token of your Storyblok space:
import { createApp } from "vue";
import { StoryblokVue, apiPlugin } from "@storyblok/vue";
import App from "./App.vue";
const app = createApp(App);
app.use(StoryblokVue, {
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.
From a CDN
Install the file from the CDN and access the methods via window.storyblokVue
:
<script src="https://unpkg.com/@storyblok/vue"></script>
Getting started
@storyblok/vue
does three actions when you initialize it:
- Provides a
storyblokApi
object in your app, which is an instance of storyblok-js-client - Loads Storyblok Bridge for real-time visual updates
- Provides a
v-editable
directive to link editable components to the Storyblok Visual Editor
Short Form
Load globally the Vue components you want to link to Storyblok in your main.js file:
import Page from "./components/Page.vue";
import Teaser from "./components/Teaser.vue";
app.use(StoryblokVue, {
accessToken: "<your-token>",
use: [apiPlugin],
});
app.component("Page", Page);
app.component("Teaser", Teaser);
Use useStoryblok
in your pages to fetch Storyblok stories and listen to real-time updates, as well as StoryblokComponent
to render any component you've loaded before, like in this example:
<script setup>
import { useStoryblok } from "@storyblok/vue";
const story = await useStoryblok("path-to-story", { version: "draft" });
</script>
<template>
<StoryblokComponent v-if="story" :blok="story.content" />
</template>
Long Form
1. Fetching Content
Inject storyblokApi
when using Composition API:
<template>
<div>
<p v-for="story in stories" :key="story.id">{{ story.name }}</p>
</div>
</template>
<script setup>
import { useStoryblokApi } from "@storyblok/vue";
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/home", { version: "draft" });
</script>
Note: you can skip using
apiPlugin
if you prefer your own method or function to fetch your data.
2. Listen to Storyblok Visual Editor events
Use useStoryBridge
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:
<script setup>
import { onMounted } from "vue";
import { useStoryblokBridge, useStoryblokApi } from "@storyblok/vue";
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/home", { version: "draft" });
const state = reactive({ story: data.story });
onMounted(() => {
useStoryblokBridge(state.story.id, story => (state.story = story));
});
</script>
You can pass Bridge options as a third parameter as well:
useStoryblokBridge(state.story.id, (story) => (state.story = story), {
resolveRelations: ["Article.author"],
});
3. Link your components to Storyblok Visual Editor
For every component you've defined in your Storyblok space, add the v-editable
directive with the blok content:
<template>
<div v-editable="blok"><!-- ... --></div>
</template>
Where blok
is the actual blok data coming from Storblok's Content Delivery API.
Check out the playground for a full example.
Features and API
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.
useStoryblok(pathToStory, apiOptions = {}, bridgeOptions = {})
This example of useStoryblok
:
<script setup>
import { useStoryblok } from "@storyblok/vue";
const story = await useStoryblok("home", { version: "draft" });
</script>
Is equivalent to the following, using useStoryblokBridge
and useStoryblokApi
:
<script setup>
import { onMounted } from "vue";
import { useStoryblokBridge, useStoryblokApi } from "@storyblok/vue";
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/home", { version: "draft" });
const state = reactive({ story: data.story });
onMounted(() => {
useStoryblokBridge(state.story.id, story => (state.story = story));
});
</script>
Storyblok API
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):
app.use(StoryblokVue, {
accessToken: "<your-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.
app.use(StoryblokVue);
Storyblok Bridge
You can conditionally load it by using the bridge
option. Very useful if you want to disable it in production:
app.use(StoryblokVue, {
bridge: process.env.NODE_ENV !== "production",
});
In case you need it, you have still access to the raw window.StoryblokBridge
:
const sbBridge = new window.StoryblokBridge(options);
sbBridge.on(["input", "published", "change"], (event) => {
// ...
});
Compatibility
This plugin is for Vue 3. Thus, it supports the same browsers as Vue 3. In short: all modern browsers, dropping IE support.
🔗 Related Links
- Add a headless CMS to Vue.js in 5 minutes: Quick-start guide on getting up and running with Storyblok and Vue.
- Storyblok & Vue.js on GitHub: Check all of our Vue.js open source repos.
- Storyblok CLI: A simple CLI for scaffolding Storyblok projects and fieldtypes.
ℹ️ More Resources
Support
- Bugs or Feature Requests? Submit an issue.
- Do you have questions about Storyblok or you need help? Join our Discord Community.
Contributing
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.