Kirby Baukasten

An opinionated, supercharged version of the Kirby Plainkit used internally at Love & Kindness for our clients' sites, with preconfigured tooling and plugins.

Note

While Kirby Baukasten is open source & used in production as base for my own projects, it's not properly versioned, and I'm not offering support for it. Instead, it should serve as a reference or guide for implementing certain best practices in your own starterkit.

Requirements

• PHP 8.2+ with composer
• Node.js 20+ with pnpm

Usage

Install Composer & Node dependencies with composer install and pnpm install.

composer install && pnpm install

Running the scaffold command with Kirby CLI

kirby baukasten:scaffold

NOTE: If you don't have the Kirby CLI installed, you will need to run composer global require getkirby/cli first.

Start the dev server.

pnpm run dev

Best Practices/Features

Styling (Tailwind CSS)

Styling is done with Tailwind CSS directly in Kirby templates or snippets.

The only pre-made change to the default theme involves switching from the Mobile-first approach to a Desktop-first approach. I do think that this is still the go-to approach for most projects.

What does this mean?

• Don’t use sm: to target all non-mobile devices
• Use unprefixed utilities to target desktop, and override them at smaller breakpoints

TypeScript / interactivity (Stimulus)

I try to avoid using TypeScript as much as possible, but some things are impossible to solve with just HTML + CSS, which is why I'm following a strict Progressive Enhancement policy when needed.

Since Kirby v4, I switched to Stimulus as framework supporting this approach. It's integrated with server-side templates exactly how I need it to be and very similiar to my own, previously used, "micro framework".

More information can be found in src ▸ controllers ▸ README.md.

Block system & the $block->attr() helper

Most of our pages are build in a page-builder-like fashion utilizing the Kirby Blocks field. To make it easier to work with, I've implemented a helper that allows you to deploy a block with a set of base attributes.

<section <?= $block->attr(['class' => 'container']) ?>>
// <section
//    class="container"
//    id="id-from-fields"
//    data-next-block="footer"
//    data-prev-block="navigation"
// >

This function is part of the tobimori/kirby-spielzeug plugin, which contains a encapsulated set of helpers & tools I use for my projects and serves as the independent foundation for Baukasten.

View Transitions (Taxi.js)

When working on fancy sites that use a lot of animations, I use Taxi.js to go the extra-mile & handle view transitions. It's a very lightweight library that has a nice API and is easy to use.

If you don't want to use Taxi:

• remove the @unseenco/taxi JS dependency
• delete the src/transitions & src/renderers folder
• remove the data-taxi & data-taxi-view attributes from layout.php
• remove the related code from src/index.ts

Code Typing

This template tries to make Kirby development more accessible by adding PHP code typing and auto completion. Sadly, this doesn't work straight out of the box.

Controllers

For controllers & other PHP files, we can add type declarations by importing the classes using PHP’s use:

<?php // site/controllers/article.php

use Kirby\Cms\App;
use Kirby\Cms\Page;
use Kirby\Cms\Site;

return function (Site $site, App $kirby, Page $page) {
  […]
}

Templates

Templates will receive variables defined by Kirby (like the $page and $kirby objects), and any other variable you return in a controller. Unfortunately, we can't declare them in PHP directly, so we need to use the PHPDoc @var tag.

<?php // site/templates/article.php

/** @var Kirby\Cms\Page $page */

<h1><?= $page->title() ?></h1>

As PHPDoc comments aren't a native PHP feature, this won't affect how our code runs, although all IDEs and most code editors (like VS Code) should support them.

Page Models

If we're using a Page Model to expand Kirby's default page object, we can use it in our templates in the same way.

<?php // site/models/article.php

class ArticlePage extends Kirby\Cms\Page {
  public function getArticleBody(): string {
    if ($this->content()->body()->isNotEmpty()) {
      return $this->content()->body()->markdown();
    }
    return '';
  }
}

<?php // site/templates/article.php

/** @var ArticlePage $page */

<h1><?= $page->title() ?></h1>
<?= $page->getArticleBody() ?>

For classes reference, check out the Kirby reference.

Auto completion in VS Code

For excellent PHP support in VS Code, we use PHP Intelephense. Follow the Quick Start instructions. Other IDEs like PhpStorm may support this out-of-the-box.

License

MIT License © 2021-2024 Tobias Möritz

Thanks to Johann for the cute banner gecko!