Create your Storyblok Field-Type Plugin using React

Contents
    Try Storyblok

    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.

    HINT:

    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}.

    app.storyblok.com
    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.

    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. 

    app.storyblok.com
    Enable local dev mode
    1

    Enable local dev mode

    Install NPM packages

    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.

    Create React component

    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.

    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.

    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>

    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.

    app.storyblok.com
    Run development server

    Run development server

    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}

    app.storyblok.com
    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.