X Close

Getting started with Craft 3.1's project config

Published on Monday, October 15, 2018

Project config is Craft's answer to a problem that just about everyone building websites with a CMS is facing: keeping settings & fields in sync across environments (local, staging, live) and across team members can be huge pain. Let's take a look at how Craft 3.1 will try to fix this.

How we solved this untill now

Imagine you've launched the website 2 months ago and now you have to add or change a field. You can change it on the live site (provided that it doesn't break things), export the live database, import that database locally, make your changes locally and then push those. Or you do everything locally first, but then you have to remember to change the settings or add the field on the live site once you deploy it. Add another or multiple teammember(s) into that mix and things are bound to go wrong.

You could write some bash scripts to make this syncing process easier, faster, less manual and thus less error prone, or use someone else's script. But in the end we're all still syncing databases.

Note that Craft's project config does not cover content or assets, so to sync those you'll still need those scripts.

Let's see how the new Project Config option works and how/if that can solve this problem.

Note that as of this writing, 3.1 is still in developer preview and should not be used for an actual project or production website.

Setting up project config in 3.1

For this post, I created a brand new Craft site, running the 3.1 developer preview and I enabled project config by adding the line below to my config\general.php.

'useProjectConfigFile' => true,

After running through the installer, Craft created a project.yaml file in the config directory of our project. We commit that yaml file to git along with the rest of our project.

Now we can start building out this supposed project. Let's start by adding a section for our homepage. Once we've created the section in the CP and we check our project.yaml file in git, we see Craft has added the new section here as well. This way, the site's structure and configuration is "recorded" in the project.yaml file.

    enableVersioning: true
        handle: home
        hasTitleField: false
        name: Home
        sortOrder: 1
        titleFormat: '{section.name|raw}'
        titleLabel: null
    handle: home
    name: Home
    propagateEntries: true
        enabledByDefault: true
        hasUrls: true
        template: index
        uriFormat: __home__
    type: single

To test what this looks like on the "other end" (your staging or production server or a coworkers machine), I cloned the git repo to another folder on my Mac and set it up as a web host too.

On the second site, we pull down the changes to project.yaml and when we refresh the CP we are prompted with a notice that tells us about configuration changes have to be applied. We click "Finish up" and the section we created in site A now also exists in site B, without us have to create it twice. Thank you project config 🙂.

This will work with sections, fields, category groups (and their fields), globals, users groups, email settings, sites & languages, etc. Plugin settings are also recorded in the project.yaml file.

Plugins may also add support for this in their own code, but this feature should only be used for things that only admin users can create or change, not for actual content. Have a look at the 3.1 dev preview notes for more details.

For teams building sites with Craft, I could certainly see this being a game changer.

I also looked at how plugin developers can support project configuration for their own data, that's something for the next post.

Will you be using project config once Craft 3.1 is out?