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.
- 🐳 Uses DDEV, a Docker-based development environment;
- ⚡️️ Vite with kirby-vite plugin;
- 🍃 CSS with TailwindCSS framework;
- 🚕 Pages transitions and preloading with Taxi.js;
- ⛰ Reactivity with Alpine.js;
- 🔎 SEO management with kirby-seo plugin;
- 🌱 Environment variables with kirby-env plugin;
- 🔥 Auto-generated type hints with kirby-types plugin;
- and more...
- Get Started
- Development
- Production
- Libraries
- User Roles
- Cookie Consent Notification (GDPR compliance)
- Acknowledgments
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
Open the .ddev/config.yaml file and update the name property to match your project's name.
This setting determines the domain for your local environment.
For example, if you set name to kirby-project, your local domain will be https://kirby-project.ddev.site.
STEP 3
On your terminal, go to your project directory and run the following commands:
# initialize Docker and all required containers
# the local domain will be given to you at the end of this process (check step 2)
ddev start# install PHP dependencies
ddev composer install# install Node.js dependencies
ddev npm installSTEP 4
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 5
Run the following command to start development mode:
ddev npm run devThis project uses Vite and TailwindCSS for frontend development.
Make sure to run the following command when in development mode:
ddev npm run devThe Kirby CLI is available to help with development. Make sure to run the following command for all available options:
ddev kirbyKirby is used as the template engine. Check the documentation.
Some recommended pages:
All assets files should be included in the assets folder in the root directory:
assets/cssfor CSS filesassets/jsfor JS filesassets/imagesfor imagesassets/fontsfor fonts
By default, a global app.css and app.js are included across the site.
- The
app.cssfile should be used for TailwindCSS; - The
app.jsfile 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.
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>Before deploying the site to production, or to check the production version locally, make sure to run the following command:
ddev npm run buildWhen deploying, set the APP_DEBUG environment variable to false:
# .env
APP_DEBUG=false- Page transitions and preloading with Taxi.js;
- Reactivity with Alpine.js;
- CSS with TailwindCSS framework;
- Helper to write better responsive design with less code using Fluid.
By default, these three user roles are available:
adminall permissions (exclusive for developers);ownersame as theadminrole, but with no access to thesystemandlanguagespanels;editorsame as theownerrole, but with no access to theuserspanel.
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.
The cookie consent notification is enabled by default and is synchronized with the settings on the Analytics panel page.
For example, if you set a Google Analytics ID, a Google tag will be added to the website, and the cookie consent notification will adapt to provide users with consent options related to Google Analytics.
Additional integrations, such as the Meta Pixel, will be included in the future as needed.
Thank you to all plugin's authors and contributors. Make sure to check and support them if you can: