Using Kirby as Headless CMS (Outdated)

Part 2 (2022) currently in the making! Lots of changes. Check out the most recent tutorial here: https://getkirby.com/plugins/getkirby/kql

Modern frontend frameworks usually don’t come with a CMS. But most of my clients want to edit the content on their website. I’ve been learning about JavaScript Frameworks in the past months and it feels fresh 😎

We will use Kirby CMS, Kirby QL, Next.js and Axios. I guess this is in my opinion the perfect stack for portfolios, blogs or just online presentations. We have a modern framework, hosted on a CDN, and a fundamentally stable and cheap backend.

But how do I connect the frontend with the backend? What backend can I use? There are plenty of tutorials on how to use a headless CMS, but most of the time it gets really frustrating. I want to have it easy and customisable as I’m used to.

We want to host the frontend— Next.js in this case — on a CDN platform. And the backend — Kirby CMS in this case — on Uberspace. It can be any shared hoster. We don’t want to spend 50$ a month just to change some images every 6 months. Uberspace is enough and starts at just 5€! (Or even 1€ 🤯) Next.js then pulls the content from Uberspace and places it into the website. The only spicy pricy is Kirby CMS with a one time fee of 99€.

Backend (Online Installation)

First we create a new Uberspace account. I can’t recommend Uberspace enough… They let you use the system for free for a month, then you just pay as much as you want. In the past years I never had one incident. Everything just works. Head over to https://uberspace.de/en/ and create an account. In the main menu page, head over to logins and provide a strong SSH password.

After that, go to datasheet and copy the url for the webspace.

Now we are ready to hit up terminal and log into the server. Always exciting! In your terminal, write

ssh username@hostname.uberspace.de

click enter and provide your SSH password when prompted.

Now we have to find the html folder. go to

cd /var/www/virtual/$USER/

and check with

ls

if you are in your home folder. If you see an html folder popping up, make sure to delete its contents with

rm -r html/*

and install Kirby with

composer create-project getkirby/starterkit html

and cd into the html folder.

cd html

Install Kirby QL

composer require getkirby/kql

This will create our interface so we can say “Hey let me get that specific content of that specific page asap 😤” and the plugin will be like “Here you go 😊”.

Last thing we need done is to create a user. nano into the Kirby configuration with

mkdir site/config
nano site/config/config.php

And paste this code:

<?php
return [
   'debug' => false,
   'api' => [
       'basicAuth' => true
   ],
   'panel' =>[
       'install' => true
   ]
];

Save the file and close nano (Mac: control + o, enter, control + x)

Now go to https://username.uber.space/ and if you see images, the installation was successful. Hit up https://username.uber.space/panel and create a user. Save the password, or just use the same as the SSH to not get confused.

After that we have the Starterkit installed and created a user. We surely have to edit Kirby in the future, but that is another tutorial itself. Since it’s a filesystem we could just make a git and push and pull back and forth. But there is also a SSH plugin for visual studio code which works surprisingly well. (https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) Alternative for Atom: https://atom.io/packages/ftp-remote-edit

Additional Info

If you want to fetch certain data like PDF’s, you’ll need a special header for this. I struggled with that one for quite some time, but I’ll share it with you here.

When logged into the server with your terminal, paste

uberspace web header set / Access-Control-Allow-Origin “*”

into (Replace the “ with the corrent quotation marks. Medium changes these here 😒)the terminal and it’ll allow another domain to access all kinds of files. Don’t ask me, I’m still confused on why images work, but PDF’s.

~~

Nowadays and personally I use laravel valet as a local server to have a better access to the code. The above Uberspace guide is cool, but if you want to have a more sustainable environment try to set laravel up.

Frontend

After the installation of Next.js, go to index.js inside the page folder.

Copy this code on the bottom of the file. getStaticProps can handle async requests which is a cool website feature. It makes sure that the page looks like something before the content - consisting of heavy images - gets loaded. Read more here: https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation

To put the data into the website, we use the props given in the return statement.

export default function Home({ data }) { …

and inside the return we can try something smooth like

{data.result.map((dat, i) => (
    <div key={i} className={styles.card}>
        <h3>{dat}</h3>
    </div>
))}

And voila, we’ve got ourselves a nice webpage:

Next update on this tutorial is gonna be dynamical created pages (static and on build time) So make sure to follow this :)

🦕

todo (maybe someone wants to help me out)

• Hide Kirby password in frontend files
• Global state
• Is prefetch still a thing?
• Routing (getStaticPaths)
• Image scrset with KQL