Custom Application

Custom Applications are the biggest of all extensions types and are the right choice if you want to extend Storyblok with some complex functionality like a Dashboard.

They will have their own location in the Space sidebar and a big window to build your own functionality similar to the popular Tasks app.

Tutorials

You can follow the How to Create an Oauth2 Authentication Flow With Koa to learn how to authenticate a custom application within Storyblok and use Storybloks Management API to edit or delete content.

Getting Started

To create a new custom application you need to be signed up as a Partner. Head into the partner portal and click on Apps {1} and then click the New button {2}. As App type select Sidebar {3} and click Create {4}.

To get started we will clone the tool plugin starter template: github.com/storyblok/storyblok-workflow-app

$ git clone https://github.com/storyblok/storyblok-workflow-app
$ cd storyblok-workflow-app
$ npm install 

We will also need to install ngrok to create a tunnel to our local application. Once you installed ngrok, you can start the tunnel to port 3000.

$ npm i -g ngrok
$ ngrok http 3000

After starting the tunnel you will need to add the tunnel HintURL to the development settings in your tool settings, like in the image below. You need a URL to the app, e.g. the tunnel URL + auth/connect/storyblok{3} and an Oauth2 callback, e.g. the tunnel URL + auth/callback{4}.

Inside the starter, you will find a .env-example file. Rename this file to .env and fill in the client id {1} and client secret {2} as well as the Oauth2 callback {4}.

.env

CONFIDENTIAL_CLIENT_ID="Id from Storyblok App"
CONFIDENTIAL_CLIENT_SECRET="Secret from Storyblok App"
CONFIDENTIAL_CLIENT_REDIRECT_URI=https://YOUR_ID.ngrok.io/auth/callback

Now we can start our development server:

npm run dev

Now if you open http://localhost:3000/ it should redirect to Storyblok, but nothing happens. In order to test it, we first need to install our tool plugin in a specific space. Open any space click on Apps {1}, My apps {2}, and then on the name of the app you created {3}.

Then click Install {1} and the App should appear in the Sidebar {2}.

Now click on the app, you will be redirected to ngrok signup page.

After signing up you'd be directed to a confirmation screen to authorize the application to have access to Storyblok. Click Approve {1}. It's important to note that once the app becomes available in the sidebar, you will be redirected to ngrok setup page to signup.

Once you authenticate your application you should be able to see the application window when clicking on the application in the sidebar {1}. If you cloned our workflow example, you should see the workflow board once it's loaded {2}.