Main navigation

Drupal 8 Config Management - how should I add config to a D8 site?

For me this is the biggest unanswered question hanging over my development of Drupal 8 websites:

How should I add config to a Drupal 8 site?

Before I go any further I should warn you that despite providing plenty of options, this article will not provide a definitive answer. After much investigation, thought and discussion I suspect different solutions will apply in different situations - I wish there was a silver bullet; a solution that is best for every situation, but (as yet) there isn't.

The problem

Imagine you are developing an existing Drupal 8 installation and you want to add, for example, a pre-existing view saved as a config file. How should you add that to your site? What about if you had 2 config files, or 10, or even 100 - how would you do it then?

The solutions(?)

The rest of this article will highlight some possible methods by which you could import config file(s).

If the migration of config is a one-time-only affair then this is a great option and the workflow is equally simple for any number of config files. BUT the development of a site is more often an iterative process - what happens when you need to add just one more config file? Simply adding this additional file to the /config/install directory of a currently enabled module will have no effect. In theory you could uninstall the module and then re-enable it, but this is not always an option if the module is a dependency of other modules. Besides this workflow is becoming cumbersome and is clearly not the intended functionality of the /config/install directory.

Configuration Synchronization

The apparent obvious solution to adding config would be the Configuration Synchronization user interface (Admin menu: Configuration > Development > Configuration Synchronization) and in some cases it is. The interface provides two options: import a single item of config or a full archive (for more details read Managing configuration in Drupal 8 on drupal.org).

Single item

The user interface for importing a single item of config is straightforward and ideal for that particular use case, but not if the number of config items increases. This workflow would not be suitable if there were, for example, ten or more items of config that required importing.

Full archive

Unfortunately, the alternative to "Single Item" is not "Multiple Items" it is "Full Archive" instead. In this case the workflow is as easy for one item of config as it would be for 100, but the steps can be complicated because this is not the prime intention of the functionality.

To add config via the Full Archive configuration synchronization the steps are as follows:

Export the complete current configuration (/admin/config/development/configuration/full/export)

Add your additional config file(s) - there are two options for doing this:

Locating the (not zipped) export of the complete config in the sync directory (by default /sites/default/files/config/sync)

Adding the additional config file(s)

Running the synchronization (/admin/config/development/configuration)

Update hook

In some cases the simplest method would be to manually convert the config file(s) into code that can be run in an update hook. This workflow would be more prone to errors due to transcribing the config, but would be ideal for simple config such as a Role, e.g.