Wanting to follow up on our work at MidCamp 2023 with the Development Settings form, Mike Herchel wanted to jam on another issue to improve the life of frontend developers. Drupal provides a way to generate themes from starterkit themes. Drupal core provides the Starterkit theme, and contributed themes can also mark themselves as a starterkit theme. All a theme has to do is have starterkit: true
in their info.yml
file. And that's it! Optionally, a specifically named PHP file can be provided in the theme for specific processing to finish generating the new theme. Unfortunately, the experience of creating starterkit themes currently involves writing a lot of PHP code to make the required file alterations. Mike opened an issue to simplify this process. This feedback arose while trying to make the Olivero theme a starterkit.
And that is how I spent my spare time at Florida DrupalCamp! I was hacking away at this issue to provide test coverage and fix a few bugs in the code. The issue was 90% of the way there, thanks to the work of Andy Blum. Getting the community to try the enhancements and provide feedback would be great!
Adding the starterkit.yml
starterkit file
Instead of relying on the starterkit: true
property in a theme's info.yml
to determine if it is a starterkit theme, there will be a new starterkit.yml
file. This allows customizations to be controlled in the starterkit when generated into a new theme. In the issue's current state, it supports four properties:
ignore
: files to ignore when generating the new theme.no_edit
: files where the contents will not be modified.no_rename
: files that won't be renamed.info
: modifications to be made to the generated theme'sinfo.yml
file.
Ignoring files
Take for example that the Olivero theme contains tests in the tests
. These tests are required for Drupal core but not when a theme is generated from Olivero. The theme also contains a post_update.php
file that executes an upgrade for existing sites. This file isn't needed for a newly generated theme, as it has never been installed.
The starterkit.yml
allows defining an array of files or glob patterns in the ignore
key. With the following in its olivero.starterkit.yml
, these files would not be copied into the new theme.
ignore:
- tests/*
- olivero.post_update.php
Additionally, glob patterns such as /js/**/*.test.js
can ignore files of a specific name in a directory and its subdirectories.
Skipping the modification of files
We have patterns to match the machine name, label, camel case, Pascal case, and title case. This is required to make sure hooks work. Taking from Olivero, the olivero_preprocess_html
hook would have to be renamed to match the new theme's name. Files must be also be renamed so that Drupal detects the theme, such as the info.yml
and .theme
files.
However, there may be specific files that should not be processed this way. Both no_edit
and no_rename
control the modification of files to handle the replacement of the starterkit's name. I am honestly torn about whether these should be two or just one operation. But this helps keep it more flexible.
no_edit: []
no_rename: []
Glob patterns such as /**/*.css
can ignore files of a specific name in a directory and its subdirectories.
I honestly cannot think of a great example of a use case for this. Perhaps if there was a starterkit named after a frontend framework, like the Tailwind CSS starterkit. If that starterkit's machine name was tailwind
versus tailwindcss
, I can see where there would be editing and renaming conflicts (example: src/tailwind.pcss
and tailwind.config.js
.)
Controlling the generated theme's info.yml
The starterkit's info.yml
will be used after being modified for naming references. The info
key allows controlling more of these values.
info:
hidden: null
version: 1.0.0
When using a null
value, the key will be removed. In the above example, it ensures the hidden
flag is removed. This will also add version: 1.0.0
to the generated theme's info.yml
.
This allows adding additional information for the generated themes that may not need to belong in the starterkit's info.yml
file. Such as providing a new default description
value if one is not provided to the generate-theme
command.
I'm available for one-on-one consulting calls – click here to book a meeting with me 🗓️
Want more? Sign up for my weekly newsletter