Skip to main content

Improving the Drupal theme starterkit and theme generation experience

Published on

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's info.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.

	- 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.

  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 🗓️