Kickstart your hosted Storyblok project in 5 minutes

You are looking for the fastest way to start your new web project or to build a proof of concept? In this tutorial, we will guide you through the Storyblok quickstart. You will be ready to start coding your website in about 5 minutes!

What you’ll do:

  1. Installing the CLI
  2. Setting up a new Space
  3. Editing a Story
  4. Calling the Content Delivery API
  5. Creating your first content component
  6. Setting up your own dev environment
  7. Creating the view layer for your first component using the rendering service

1. Installing the CLI

The CLI will help you bootstrapping your new space in a few seconds.

npm install -g storyblok

2. Setting up a new Space

Using the following command you can setup a Space and also opens your first [Story] which is called “home”.

storyblok quickstart

If you didn’t signup already you can directly register yourself during the quickstart.

Storyblok Quickstart Questions

3. Editing a Story

You may wonder what happened - during the quickstart command the CLI logged you in in your default browser & also created a Space with your first Story “home”. The screen you will see at first is the Storyblok side-by-side editor. On the left side, you will see the sidebar - in which you can create new components, add content & nest them as you want. The right side of this screen is nothing more than an iframe including your website - at that specific moment - the freshly cloned quickstart theme hosted on your very own subdomain of Storyblok!

Bootstrapped Quickstart

4. Calling the Content Delivery API

Let’s continue with the first step in the quickstart tutorial - your first API request. We’ve prepared many examples in your programming language of choice. Pressing on “Send” will do that request for you instantly and you will see how a basic Story actually looks like.

{
  "name": "home",
  "created_at": "2017-06-23T10:41:33.887Z",
  "published_at": "2017-06-22T06:33:05.745Z",
  "id": 48472,
  "uuid": "19ccc8ca-55f5-4759-a787-b9759e31d270",
  "content": {
    "_uid": "8ed09781-a786-407f-8d80-b651ccbbbdf6",
    "body": [],
    "component": "root"
  },
  "slug": "home",
  "full_slug": "home"
}

5. Creating your first content component

What would a CMS for components be without component? Let’s start creating our first component - which we will call teaser in this tutorial. You can let yourself guide through the Storyblok Interface by pressing the Start tour - you can also have a look at the image below.

Let’s see what has changed by simply doing another API request.

{
  "name": "home",
  "created_at": "2017-06-23T10:41:33.887Z",
  "published_at": "2017-06-22T06:33:05.745Z",
  "id": 48472,
  "uuid": "19ccc8ca-55f5-4759-a787-b9759e31d270",
  "content": {
    "_uid": "8ed09781-a786-407f-8d80-b651ccbbbdf6",
    "body": [
      {
        "_uid": "d651d8cd-1f0f-4de0-8c5b-851d0b5ddc94",
        "headline": "",
        "component": "teaser",
        "_editable": "<!--#storyblok#{\"name\": \"teaser\", \"space\": \"40612\", \"uid\": \"d651d8cd-1f0f-4de0-8c5b-851d0b5ddc94\", \"id\": \"48472\"}-->"
      }
    ],
    "component": "root"
  },
  "slug": "home",
  "full_slug": "home"
}

As you can see the body of the automatically created root component now contains a component called teaser with the attribute headline! You can add more fields with different types and fill your component with content.

6. Setting up your own dev environment

Choose to get the content via the API or using the hosted rendering service. Since we want to create a view layer using the rendering service we will go with that - but you can, of course, checkout the API/SDK as well so you can integrate Storyblok in your current technology stack!

Storyblok - choose API/SDK only or the rendering service

We already have the CLI installed so we can skip this and directly configuring the quickstart for the current space. Choose a folder in which the github repository of the quickstart should be cloned and configured for your local development.

Downloading and configuring your local dev environment

After entering storyblok quickstart --space={{YOUR_SPACE}} - the CLI will checkout the GitHub repo and directly configures it with the right tokens, subdomains and access tokens - all what is left is to open the project in your favourite editor and running the startup command cd ./my-project && npm install && npm run dev.

The last command will start a local web server on the port :4440 for you so you won’t have to worry about that - you can still customize the whole workflow using gulp and you can always start the web server by simply using npm run dev in that directory.

cd ./{{YOUR_PROJECT}} && npm install && npm run dev

As you can see this command will open the side-by-side editor as well - the main difference it changed the frame on the right side to your local web-server with instant reload! You can switch between environments at the left bottom corner in the Storyblok editor.

7. Creating the view layer for your first component using the rendering service

Make sure you let your local web-server running while you’re opening the source in your favorite editor and following the last step - adding a view to the teaser component!

As you’ve created the _teaser.liquid - the web server in the background directly submit’s that file to the rendering service and because the name of your component in Storyblok and in the code is the same - the rendering service directly does the data matching for you and fills the teaser with the input of your teaser! You can create multiple instances of your component with different data of course. You can create new components - with a completely different set of fields and even nested components for a complex grid layout or similar!

Summary

What did you learn/achieve - you’ve:

  1. ✓ installed the CLI
  2. ✓ created your first Space
  3. ✓ edited your “home” Story
  4. ✓ called the content delivery API
  5. ✓ created your very own teaser component
  6. ✓ a local dev environment for your space
  7. ✓ hosted your first project on a subdomain using the rendering service

You can now create your own set of components and build your whole page, blogs or similar!

Final reuslt

I hope you enjoyed this tutorial and I would be happy to receive feedback! You can find the source code using the release list on Github: Kickstart - Releases.

Next: Learn how to create a grid layout

You are looking for a way to create a website with a grid layout? You won’t start all over with one of the old CMS which force you into a certain technology stack? In this tutorial we will guide you through the creation of a grid layout using…


More to read...

About the author

Dominik Angerer

A web performance specialist and perfectionist. After working for big agencies as a full stack developer he founded Storyblok. He is also an active contributor to the open source community and one of the organizers of Stahlstadt.js.