Development

Prerequisites

This guide requires the following applications to be installed on your machine:

Node.js LTS
Yarn
NPM 5.2.0 or above
Git

Create a project

To create a new project, run Storyblok’s field plugin command line interface. This will run a setup wizard, letting you choose between different options.

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

After choosing a package manager, choose whether the new project should be a monorepo or a polyrepo. If you are unfamiliar with the concept of a monorepo, choose polyrepo.

LEARN: A monorepo is a software development strategy in which the code for a number of projects is stored in the same repository. A polyrepo is the opposite – a repository with a single project.

Next, choose a package name. In this example, it will be “training-field”. Finally, select a template for one of the following frameworks:

Vue 2
Vue 3
React
JavaScript

Run locally

Navigate into the newly created directory:

cd training-field/

Start the application:

npm run dev

In the terminal, a list of URLs will be returned. Open the Sandbox URL in your webbrowser. Here, you can view your field plugin during development.

LEARN: The Plugin Sandbox emulates the Visual Editor, letting you view the field plugin while developing.

Deploy

In the project folder, build the application:

npm run build

To deploy the field plugin, run the following command:

npx @storyblok/field-plugin-cli@latest deploy

If the environment variable STORYBLOK_PERSONAL_ACCESS_TOKEN is not defined yet, you will be prompted to provide a personal access token. To issue a new personal access token, navigate to My account > Personal access token in Storyblok. The CLI optionally lets you save the token as a local environment variable.

Choose where to deploy the plugin:

My plugins: These field plugins are tied to one individual user. Only that user can manage the plugin.
Partner Portal: These field plugins are tied to an organization. Anyone in this organization can manage the plugin.
Organization: These field plugins are tied to an organization.

Finally, choose a name. If the name does not exist yet, you can confirm the deployment. If the name is already taken, you can update the existing field plugin, or create a new one.

Upon successful deployment, a link to the field plugin editor is provided and the plugin is available in Storyblok.

Field plugin editor

Opening the link reveals the field plugin editor.

The field plugin editor consists of various components. The large text area on the left hand side shows the content of the deployed bundle, i.e. the script that will be inserted into the iframe document.

The Options section contains the default options and their values. The values are only accessible during development. The keys inform admin users in a space about the available options for a plugin.