Almost EVERYONE who tried headless systems said they saw benefits. Download the state of CMS now!

O’Reilly Report: Decoupled Applications and Composable Web Architectures - Download Now

Empower your teams & get a 582% ROI: See Storyblok's CMS in action

Skip to main content

Create your Storyblok Field-Type Plugin using React

Try Storyblok

Storyblok is the first headless CMS that works for developers & marketers alike.

  • Home
  • Tutorials
  • Create your Storyblok Field-Type Plugin using React

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.

HINT:

If you are in a hurry, you can take a look at the code in this GitHub repository.

Section titled What's Vuera? 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.


Section titled Configure the plugin in the Storyblok space 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
1
2
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.


Section titled Create Vue app 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.

src/Plugin.vue
        
      ...

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
1

Enable local dev mode

Section titled Install NPM packagesundefined Install NPM packagesundefined

For this example we'll need to install three packages in our Vue application. Inside the project folder, run the following command in the Terminal:

        
      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.

Section titled Create React componentundefined Create React componentundefined

Inside the src folder, let's create a file called MyReactComponent.jsx:

src/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.

Section titled Include the React component in the Vue pluginundefined Include the React component in the Vue pluginundefined

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.

src/Plugin.vue
        
      <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>
    

Section titled Include Vuera in the main script Include Vuera in the main script


Let's go to the main.js file and import the element VuePlugin from vuera. Let's use it in our vue application inside the Storyblok object: 

src/main.js
        
      ...

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

Run development server

Section titled Deploy the plugin Deploy the plugin


After we finished developing the plugin we need to run npm run build and copy the content of the file dist/export.js into the editor text field inside the Storyblok application {1}, Save {2} and click on the Publish button {3}

Deploy plugin
1
2
3

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.

Author

Facundo Giuliani

Facundo Giuliani

Facundo is a Developer Relations Engineer at Storyblok. From Buenos Aires, Argentina, he has more than 15 years of experience in software development. Full Stack Developer. Auth0 Ambassador. Prisma Ambassador. Cloudinary Media Developer Expert. He is also an open-source contributor.