Skip to content

Introduction to Tool Plugins

Tool plugins extend the Visual Editor as standalone applications that Storyblok embeds in iframes within the Tools sidebar. The plugins communicate with Storyblok through cross-window messaging and the Management API.

Content editors open tools directly from the Visual Editor. For example, the Smartling plugin requests a translation job for the story that an editor has open and imports the translated content back into Storyblok.

Tool plugins are similar to space plugins but differ in key ways. Namely, tool plugins embed directly in the Visual Editor and can access the story while editing.

Tool plugins require self-hosting, and only users with access to the Partner Portal or an organization can register them.

First, create a new tool plugin: in the Partner Portal or your organization open Extensions → Tools, and select Create new.

Name the plugin, enter a unique string in the ID/Slug field (the plugin sends the slug in its messages to the Visual Editor), and Save.

To communicate with Storyblok, open the plugin, select OAuth 2.0 and Pages, and check the following:

Setting Description
Client Identifier and Client Secret Use as environment variables in your application.
Index to your page and Redirection endpoint Define the URLs in the Production and Preview sections based on your app’s hosting domain.
  1. In the General tab, copy the Install Link.
  2. Open the URL in your browser, and select a space to install the plugin.

To display the plugin in the Visual Editor, run the plugin locally and enter the local URLs in the OAuth 2.0 and Pages settings. The first time someone opens the plugin, Storyblok shows the OAuth consent screen. An admin has to approve the plugin before editors can use the plugin.

Your plugin is currently a standalone app embedded in Storyblok. To connect it to the Visual Editor, use the postMessage() method.

This allows the plugin to respond to changes in the story. The following snippets include some practical examples.

Tools appear stacked vertically in the Visual Editor, with iframes set at a specific height in pixels. When the height of your tool changes (for example, on initial load), instruct the Visual Editor to adjust the iframe height:

window.parent.postMessage(
{
action: "tool-changed",
tool: "my-tool-plugin-name",
event: "heightChange",
height: 500,
},
"https://app.storyblok.com"
);

Storyblok manages the stacking order, so use minimal vertical space to keep the tools below visible.

To adjust the height automatically, use ResizeObserver and update the iframe height when the document height changes. In your CSS, set the html element’s height to auto:

html {
height: auto;
overflow: hidden;
}

Update the component’s code:

const handleResize = () => {
const height = document.body.clientHeight;
window.parent.postMessage(
{
action: "tool-changed",
tool: "my-tool-plugin-name",
event: "heightChange",
height,
},
"https://app.storyblok.com"
);
};
const observer = new ResizeObserver(handleResize);
observer.observe(document.body);
// Use the `disconnect()` method to stop observing the component:
observer.disconnect();

To read the story in the Visual Editor, create an event listener that only accepts messages from Storyblok:

const handleMessage = (event) => {
if (event.origin !== "https://app.storyblok.com") return;
console.log(event.data);
};
window.addEventListener("message", handleMessage, false);
// Remove the listener when you clean up the component:
window.removeEventListener("message", handleMessage, false);

And send a message to request context:

window.parent.postMessage(
{
action: "tool-changed",
tool: "my-tool-plugin-name",
event: "getContext",
},
"https://app.storyblok.com"
);

The JSON response from the Visual Editor contains the full story context:

{
"action": "get-context",
"story": {},
"language": "default",
"releaseId": 12345,
"releases": []
}

To reflect content updates in the Visual Editor preview, create a handleReloadStory function that reloads the preview. Call it after the story update, for example, via a button click.

const handleReloadStory = () => {
window.parent.postMessage(
{
action: "content-changed",
tool: "my-tool-plugin-name",
event: "reloadPreview",
},
"https://app.storyblok.com"
);
};

Server-side code reads the accessToken, region, and spaceId of the current space and user from the session that the @storyblok/app-extension-auth library stores.

Storyblok adds the space_id and user_id query parameters to the plugin URL, and inferSessionQuery() reads them from the request.

Pass the same parameters you pass to authHandler as authHandlerParams:

import { getSessionStore, inferSessionQuery } from "@storyblok/app-extension-auth";
const sessionStore = getSessionStore(authHandlerParams)({ req, res });
const appSessionQuery = inferSessionQuery(req);
const { accessToken, region, spaceId } = await sessionStore.get(appSessionQuery);

To call the Management API, send requests that reference the same values. The following example lists the stories in the space:

new StoryblokClient({
oauthToken: `Bearer ${accessToken}`,
region,
}).get(`spaces/${spaceId}/stories`, {
sort_by: "updated_at:desc",
});

To match the Visual Editor’s interface, use Storyblok’s design system for Vue 3 (npm install @storyblok/design-system) or Storyblok MUI for React-based frameworks.

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.