Migration to Vue 3

In 2023, Storyblok launched a new SDK for developing field plugins. While older field plugins only worked with Vue 2.5, the new SDK lets you develop with any frontend framework, including Vue 3 and React. The new SDK also has newer features, in-depth documentation, TypeScript support, and is actively maintained. This tutorial guides you through the process of upgrading a legacy field plugin from Vue 2.5 to Vue 3.

Prerequisites

• Node.js LTS
• Yarn
• NPM 5.2.0 or above
• Git

Understanding the legacy field plugin

The simplistic version of legacy field plugin may look like this:

const Fieldtype = {
  mixins: [window.Storyblok.plugin],
  template: `<div><input v-model="model.example" /></div>`,
  methods: {
    initWith() {
      return {
        plugin: 'test-field-plugin',
        example: 'Hello World!'
      }
    },
    pluginCreated() {
      console.log('plugin:created')
    }
  },
  watch: {
    'model': {
      handler: function (value) {
        this.$emit('changed-model', value);
      },
      deep: true
    }
  }
}

Whenever model changes, it emits a changed-model event to its parent. There is a hidden parent component that is automatically injected by Storyblok. It receives this event and forwards it to the Visual Editor via postMessage. All communication occurred using $emit('some-event').

Understanding the new field plugin

We no longer recommend creating a field plugin directly in the field plugin editor. Instead, we provide a new CLI that helps you create one. To do so, run the following command and select the Vue 3 template.

npx @storyblok/field-plugin-cli@latest create --template vue3

In the newly created project folder, open the src/components/FieldPluginExample/Counter.vue file.

const {
  data,
  actions: { setContent },
} = useFieldPlugin()

// ...

setContent(value)

Most importantly, this.$emit('changed-model', value) is now plugin.actions.setContent(value).

The Vue 2 component above will become like the following:

src/components/Fieldtype.vue

<script setup>
import { useFieldPlugin } from '@storyblok/field-plugin/vue3'

const plugin = useFieldPlugin()
</script>

<template>
  <div>
    <input
      :value="plugin.data.content"
      @input="plugin.actions.setContent($event.target.value)"
    />
  </div>
</template>

Getting data

In the legacy version, the mixin injected all the data into this of the root component.

const Fieldtype = {
  mixins: [window.Storyblok.plugin],
  template: `<div><input v-model="model.example" /></div>`,
  methods: {
    initWith() {
      return {
        plugin: 'eltest-0707',
        example: 'Hello World!'
      }
    },
    pluginCreated() {
      console.log('plugin:created')
    }
  },
  watch: {
    'model': {
      handler: function (value) {
        console.log('💡 data', {
          blockId: this.blockId,
          contentmodel: this.contentmodel,
          model: this.model,
          schema: this.schema,
          spaceId: this.spaceId,
          storyId: this.storyId,
          storyItem: this.storyItem,
          token: this.token,
          uid: this.uid,
          userId: this.userId,
        });
        this.$emit('changed-model', value);
      },
      deep: true
    }
  }
}

However, with the useFieldPlugin, it's much simpler:

const plugin = useFieldPlugin();console.log(plugin.data);

Actions

Due the introduction of the useFieldPlugin composable, you run actions differently.

Set Content

// before
this.$emit('changed-model', value);

// after
const plugin = useFieldPlugin();
plugin.actions.setContent(value);

Toggle Modal

// before
this.$emit('toggle-modal', booleanValue);
// after
const plugin = useFieldPlugin();
plugin.actions.setModalOpen(booleanValue);

Getting Current Context

// before
this.$emit('get-context');
this.$onGetContext(() => {
  console.log(this.storyItem);
})

// after
const plugin = useFieldPlugin();
plugin.actions.requestContext(); // this updates `plugin.data.story` asynchronously, which triggers a re-render.

Asset Selector

// before
// You had to include this proxy component:
<sb-asset-selector :uid="uid" field="your_model_attribute"></sb-asset-selector>

// after
const plugin = useFieldPlugin();
const asset = await plugin.actions.selectAsset();
console.log(asset.filename);

Summary of changes

• Added content: In the legacy version, you had to send an object containing plugin property (e.g. { plugin: "my-plugin", some: "value" }). Unlike before, now content can be anything: string, boolean, number, object, array, etc. You can use anything as long as it can be serialized. Pass content from a field plugin to Storyblok's Visual Editor via postMessage. To learn more about what you can send, read the structured code algorithm.
• Removed initWith: initWith was a method called by the mixin window.Storyblok.plugin. Thanks to the useFieldPlugin composable, it is no longer required.
• An empty string is given to your field plugin at plugin.data.content by default.
• Removed pluginCreated: You can use the regular lifecycle callbacks such as onMounted().
• Removed default style: A default css file used to be injected (https://plugins.storyblok.com/assets/css/index-latest.css). With the new version, you have full control over the styling.
• Removed api: The storyblok-js-client is no longer included by default. You can include it by running npm install storyblok-js-client.
• Removed $sb

API Reference

To learn more about all the APIs, you can read the API Reference.