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;
- TailwindCSS;
- Live reloading for
templates,snippets,contentandassetschanges; - SEO management with kirby-seo plugin;
- Environment variables with kirby-env plugin;
- Development tools:
- Debug bar with kirby-debugbar plugin;
- Auto-generated type hints with kirby-types plugin.
- and more...
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 containersddev composer install # install PHP dependenciesddev npm install # install Node.js dependenciesSTEP 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 launchThis 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=falseBy default, these three user roles are available:
adminexclusive for developers;ownerfor the client, with all permissions;editorsame as theowner, but with no access to the users panel.
Since the admin role is intended for the developers only, it will be invisible to users with the owner and editor 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
]
];Also, both the owner and editor roles have no access to the system and languages panels.
If you want to change these permissions, edit the files at site/blueprints/users to your needs.
By default, and for GDPR and CCPA compliance, a cookie consent notification is enabled and will show when you visit a page. To check the full list of integrations available check the Integrations section below.
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.
- Google Consent Mode v2
If you want to add Google Analytics to your site and be compliant with GDPR and CCPA regulations,
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=nullAll SEO robots information is hidden by default and only visible to admin users.
This is due to the leading to confusion to clients that do not understand what it does.
If you want to change this behavior, just change the following code to your needs:
// config.php
return [
'ready' => function(Kirby $kirby) {
$user = $kirby->user();
return [
'tobimori.seo' => [
'robots' => [
// show robots settings to admins only
'pageSettings' => $user?->isAdmin() ?? false,
'indicator' => $user?->isAdmin() ?? false
]
]
];
}
];More information at the official documentation page.
Thank you to all plugin's authors and contributors. Make sure to check and support them if you can: