Skip to content

A very opinionated Kirby CMS development stack with DDEV, Vite and TailwindCSS

Notifications You must be signed in to change notification settings

programmatordev/kirby-starter

Repository files navigation

Kirby Starter

A very (very!) opinionated Kirby CMS development stack.

Important

This project is intended for internal use. This means that the development approach will always be in virtue of how we work with our clients or our own projects, and you may disagree with them. Still, we are open for discussion, so feel free to ask for any features or changes. We just want to be clear in advance.

Features

  • Uses DDEV, a Docker-based development environment;
  • Vite with kirby-vite plugin;
  • TailwindCSS;
  • Live reloading for templates, snippets, content and assets changes;
  • Page transitions;
  • SEO management with kirby-seo plugin;
  • Environment variables with kirby-env plugin;
  • Development tools:
  • and more...

Documentation

Get Started

Before starting, make sure you have DDEV installed. If not, follow their instructions here.

STEP 1

Download this project to a directory of your choosing.

STEP 2

On your terminal, go to your project directory and run the following commands:

ddev start # initialize Docker and all required containers
ddev composer install # install PHP dependencies
ddev npm install # install Node.js dependencies

STEP 3

Include a .env file in your project root. A .env.example file already exists, so you can either rename it or create a new one.

STEP 4

To launch the project in the browser, run the following command:

ddev launch

Development

This project uses Vite and TailwindCSS for frontend development.

Make sure to run the following command when in development mode:

ddev npm run dev

Kirby CLI

The Kirby CLI is available to help with development. Make sure to run the following command for all available options:

ddev kirby

Template System

Kirby is used as the template engine. Check the documentation.

Some recommended pages:

Assets

All assets files should be included in the assets folder in the root directory:

  • assets/css for CSS files
  • assets/js for JS files
  • assets/images for images
  • assets/fonts for fonts

CSS and JS Assets Handling

By default, a global app.css and app.js are included across the site.

  • The app.css file should be used for TailwindCSS;
  • The app.js file should be used for JavaScript code across all pages of the site.

To include other global CSS and JS files, use the following code in the <head> of your layout:

<?= vite().css('path/to/file.css') ?>

For JS files, always include defer for optimal performance:

<?= vite().js('path/to/file.js', ['defer' => true]) ?>

To include CSS and JS files in a specific page, use the existing slots for that purpose:

<?php slot('styles') ?>
    <?= vite().css('path/to/file.css') ?>
<?php endslot() ?>

<?php slot('scripts') ?>
    <?= vite().js('path/to/file.js', ['defer' => true]) ?>
<?php endslot() ?>

<?php slot('content') ?>
    <!-- HTML page content... -->
<?php endslot() ?>

More information about slots.

Static Assets Handling

To add static assets to a page (images, fonts, etc.) use the following code:

<?= vite().file('path/to/file.svg') ?>

Examples:

<img src="<?= vite().file('path/to/file.svg') ?>" alt="Image">
<link rel="preload" href="<?= vite()->file('path/to/font.woff2') ?>" as="font" type="font/woff2" crossorigin>

For images in CSS, always enter the path of the image relative to the CSS file.

Using Tailwind, considering that CSS files are in assets/css and images are in assets/images, an example would be:

<div class="aspect-square bg-[url('../images/file.jpg')]"></div>

Production

Before deploying the site to production, or to check the production version locally, make sure to run the following command:

ddev npm run build

When deploying, set the APP_DEBUG environment variable to false:

# .env

APP_DEBUG=false

Page Transitions

A page transition manager is implemented by default using taxi.js.

The following code in the app.js file handles this for you. If you do not want to use page transitions, just remove it:

// assets/js/app.js

// handle page rendering and transitions
const taxi = new Core({
    renderers: { default: DefaultRenderer },
    // a fadein/out transition is enabled by default
    // to create your transition go to the assets/js/transitions folder for examples
    transitions: { default: FadeTransition }
});

Check the taxi.js page for all available options and advantages of using it.

User Roles

By default, these three user roles are available:

  • admin all permissions (exclusive for developers);
  • owner same as the admin role, but with no access to the system and languages panels;
  • editor same as the owner role, but with no access to the users panel.

Since the admin role is intended for developers only, it will be invisible to all other roles. This is, the users with this role will not appear in the users panel and searches, or be accessible.

To disable this behavior, set the hideAdminUsers to false:

// config.php

return [
    'programmatordev.users-extended' => [
        'hideAdminUsers' => false
    ]
];

If you want to change these permissions, edit the files at site/blueprints/users to your needs.

Cookie Consent Notification

By default, and for GDPR and CCPA compliance reasons, a cookie consent notification is enabled. A list of integrations is available, so check the Integrations section below.

The consent notification comes with 5 categories:

  • necessary
  • measurement
  • marketing
  • functionality
  • experience

All categories are disabled by default, except the necessary category which is always enabled.

If an integration is used, the categories related to that integration will be enabled. For example, if Google Analytics is integrated, the measurement and marketing categories will be enabled and synced according to user preferences.

If you do not need a cookie consent notification, just remove the following snippet from the master layout:

// snippets/layout.php

// remove this line from the <head> block
<?= snippet('consent/notification') ?>

For the full cookie consent options, visit the plugin page.

Integrations

List of currently available integrations:

Google Analytics

If you want to add Google Analytics to your website and be compliant with GDPR and CCPA regulations, just set the CONSENT_GOOGLE_TRACKING_ID in the .env file.

# set Google tracking id (G-XXXXXXXXXX/AW-XXXXXXXXXX) to sync cookie consent with analytics and ads
CONSENT_GOOGLE_TRACKING_ID=G-1234567890

Syncs with the mesaurement and marketing consent notification categories.

Acknowledgments

Thank you to all plugin's authors and contributors. Make sure to check and support them if you can: