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; - Page transitions;
- 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...
- Get Started
- Development
- Production
- Page Transitions
- User Roles
- Cookie Consent Notification (GDPR & CCPA 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
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=falseA 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.
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.
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:
necessarymeasurementmarketingfunctionalityexperience
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.
List of currently available integrations:
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-1234567890Syncs with the mesaurement and marketing consent notification categories.
Thank you to all plugin's authors and contributors. Make sure to check and support them if you can: