Home Blog Building a Craft CMS scaffolding package

Building a Craft CMS scaffolding package

When I posted about the Craft CMS starter repo we created at work, a couple of people were very interested in how to build something like that for themselves.

So’s have a look at how we’ve done things.

Not that this is not a step-by-step or line-by-line walkthrough but more a high-level overview with some examples. If you're trying this out for yourself and you're stuck on something, feel free to get in touch and I'll try help you out 🙂

Screenshot of our custom Craft install script

(We call our starter repo our “base install” so that’s what I’ll be calling it in the post)

composer create-project

We’ll be relying on Composer’s create-project command to turn our site repository in our “base install” repository. Running the command, (eg composer create-project statikbe/craft) will clone the repository and run composer install afterwards.

That means that the repository you start from should have all the plugins, templates, etc you want to have installed when starting a new project.

For your repository to work with composer, you have to register it with Packagist. In our case, that means it's a public Github repo.

Project config

In Craft CMS 3.1, the project config feature was added. When project config is enabled, site & plugin settings are written out to a yaml file, making it easier to share settings between environments.

In the case of our base install, we’re using project config to seed our new project with the settings/sections/fields we have in that base install. That way, we can change/fix/improve things in the CP and commit those changes, to use them in the next project.

How to install

Let’s take this step by step. composer create-project statikbe/craft path/to/folder This will:

Clone the base install in the folder of our choosing
Run composer install, based on the composer.json we have in our base install
Run the commands we’ve specified in the post-create-project-cmd. In our case that is:

Copy over .env.example to .env
Copy over .gitignore.example to .gitignore
Run composer dum-autoload
Run ./craft setup/welcome to remind users what to do next

Then we install Craft CMS, like we would in any other project. This can be done in the browser or through the command line. We’ll use the later since that’s what we’re using already.

./craft setup

This will run through the regular Craft installer (asking you for database credentials, installing Craft, creating a user).

At the very end of this process, the install will check if you have project config enabled ('useProjectConfigFile' => true in config/general.php and if a project.yaml file is present, both are true in our case). It will then try to apply the settings from that project config file to the newly installed Craft site you just created, meaning it will install plugins, create sections, create fields, etc, making it so that our new project now has all the same settings/sections/fields/plugins as our base install.

📣 If the settings from your project config are not being applied, search Craft’s logs for can't apply existing project config: and that should tell you what went wrong.

After Craft’s install script, we added one of our own. Let’s have a look at that now.

Our custom install script

The install script we have in our repository can be run by entering ./craft statik/setup , which translates to “running actionIndex from console\controllers\SetupController in the Statik module”.

The first important thing to keep in mind is that in this part of the installation process of our new site, Craft CMS is already installed and we can leverage it where needed. Like we do by running a console command from a module.

And the second trick up our sleeve is environment variables. More on that later.

You can fellow along with our controller here as we have a look at a couple of examples of command you can do.

We could add these options and values in 1 large script, but part of making this reusable across projects (and for possibly for other people) means that we wanted to have options as to what we use where & how.

Disabling project config.

While we use project config to manage settings in our base install and we have to have it enabled there, we don’t use it in our actual projects. So in our setup script we have an option to disable it.

Step 1 is to have to config setting set to an environment variable, like so: 'useProjectConfigFile' => getenv("PROJECT_CONFIG") ?? false

Step 2 is asking the question in our setup script.

In our case, we ask if you want to disable the setting, with the default being true. You can phrase it the other way around or ask just about anything you can think of. You’ll get a boolean value in return and based on that you can proceed or do your thing. In our case that thing is setting an environment variable.

Adding placeholder images

The other example we’ll look at is the function we use to add our placeholder images:

(You can find the $this->executeShellCommand we’re using in this function in the same class right here)

The idea behind this function/question in our installer is that we want to add a set of placeholder images to our new site. As you can see in the repository, we have 4 placeholders in there. When you choose to add the placeholders, the command will:

Create a test folder in our /files volume
Copy over the placeholder files to that test folder
Removed the original placeholders folder
Run ./craft index-assets/all to re-index all assets, thereby adding the files we just copied to the CMS
These are just 2 example of questions we ask during our installation script, you can find the entire script/controller here.

Moving the different questions/functions to a service is probably cleaner and something that is on our to-do list

I hope this write-up helped out a couple of people that want to try setting up something like this 🙂. If you have any feedback or questions, feel free to tweet me, email me or ping me on the Craft Discord server.