Create your Storyblok Field-Type Plugin using React
Storyblok is the first headless CMS that works for developers & marketers alike.
Did you know that it's possible to develop Storyblok field-type plugins using React? Vuera makes the magic! Let's see how to create a React component, insert it into a Vue application, and integrate the plugin into Storyblok to enhance the real-time Visual Editor.
If you are in a hurry, you can take a look at the code in this GitHub repository.
What's Vuera?
Vuera is an NPM package that allows us to use React components inside a Vue application. As the Storyblok platform was created using Vue, the interface exposed to create plugins and custom applications follows the same technology stack. So, If we want to create a React field-type plugin and install it on our space, Vuera comes into play to give us the possibility of expanding the behavior of the Storyblok application.
Configure the plugin in the Storyblok space
To configure our new plugin, let's go to Storyblok app. Go into the Account {1} menu, and click on Plugins {2}. We should create a new field-type by clicking the New button {3}.
)
Create new plugin
We have to enter a unique name slug, and then we will be redirected to the Plugin Editor. Once we are inside the Plugin Editor, we should follow the steps detailed in this guide to inject, create, configure, and install our field-type plugin: https://www.storyblok.com/docs/plugins/plugin-interface.
We can also create plugins inside the Partner Portal, so they are available for all the spaces of our organization.
Create Vue app
The field-type plugins in Storyblok are Vue components extended with a few helpers in the window.Storyblok.plugin variable.
Storyblok offers a Plugin Editor where you can create the code for the plugins. In case you want to work locally and test your project before uploading it to Storyblok, you can set up a local development mode. To do that, let's execute these commands in the Terminal:
git clone https://github.com/storyblok/storyblok-fieldtype
cd storyblok-fieldtype
npm install
If we run npm run dev it will start a server on http://localhost:8080.
Inside the file src/Plugin.vue, let's change the plugin name in the initWith method to the one we created in Storyblok.
...
initWith() {
return {
plugin: 'react-field-type-plugin',
title: '',
description: ''
}
}
...
Now, we should click the checkbox Enable local dev mode {1} inside the Storyblok application. That will allow us to preview and edit the plugin that we are running locally.
)
Enable local dev mode
npm install react react-dom vuera
The first two are the default packages we need to install in order to create a React application or component. The third package is the one we mentioned before that will help us inject that React component inside of a Vue application.
Create React component
Inside the src folder, let's create a file called MyReactComponent.jsx:
export default (data) => {
return (
<div>
{data.props.title}
</div>
)
}
This React component will be the core of our plugin. The idea of this tutorial is to show how to setup a field-type plugin using React, feel free to expand the behavior and features of this very simple example.
Include the React component in the Vue plugin
Open the src/Plugin.vue file, and let's import our newly React component. Let's use it inside the <template> element, and include the components property in the default export of the file.
<template>
<div class="uk-form-row">
<label>React field:</label>
<my-react-component :title="model.title" @update="update" />
</div>
</template>
<script>
import MyReactComponent from "./MyReactComponent";
export default {
mixins: [window.Storyblok.plugin],
components: { "my-react-component": MyReactComponent },
methods: {
initWith() {
return {
plugin: "react-field-type-plugin",
title: "Plugin Title",
description: "Plugin Description",
};
},
pluginCreated() {
console.log(
"View source and customize: https://github.com/storyblok/storyblok-fieldtype"
);
},
},
watch: {
model: {
handler: function (value) {
this.$emit("changed-model", value);
},
deep: true,
},
},
};
</script>
...
import { VuePlugin } from 'vuera'
window.Storyblok.vue.use(VuePlugin)
if (process.env.NODE_ENV == 'development') {
...
Now, we can run the development server and verify that our plugin is working locally.
)
Run development server
)
Deploy plugin
And that's it! We have a new field-type plugin available to be used inside the Storyblok real-time Visual Editor, created using a React component.
| Resources | Link |
|---|---|
| GitHub demo repository | https://github.com/storyblok/storyblok-fieldtype-react |
| Vuera NPM package | https://www.npmjs.com/package/vuera |
| Field-Type Plugin docs | https://www.storyblok.com/docs/plugins/field-type |
| Field-Type Plugin starter | https://github.com/storyblok/storyblok-fieldtype |
