How to export configuration for a quickstart module during pull request creation - az-digital/az_quickstart GitHub Wiki

Context

Oftentimes we need to add configuration as code in order to create a new feature that is to be distributed in Quickstart.

When developing for Quickstart, we use local development tools like ddev or lando.
The Quickstart development tooling (ddev and lando configuration) comes with things like:

  • PHPUnit
  • PHPStan
  • ESLint
  • Prettier
  • Theme Debug mode
  • Drush

You can see all of the available lando tooling simply by typing lando and pressing the return key within your Command Line Interface (CLI) console.

Note: Drupal Console was removed in Drupal 10. Use the Drush commands below instead of drupal config:export:single.

First we need to download and install the Quickstart codebase, and create a new branch using an issue number.
Then we need to turn on lando, or ddev.
Then install Quickstart in the containers that lando or ddev provide.
Now we can navigate around our local development site as if it is a site online.

What is configuration as code?

Tip: Generally you know that you will need to export configuration if you see a machine name setting when editing the configuration.

Other times, it isn’t clear that you are creating config; however, you can usually deduce that something is configuration (and should be exported) if it is not content. One example is changing entity type display settings.

How to export config for use in Quickstart

There are two common workflows. Choose the one that matches your task:

  1. Export config into a custom Quickstart module
  2. Export config back into the Quickstart distribution

1) Export config into a custom Quickstart module

If you are building a custom Quickstart module (for example, starting from azqs_module_project), use the single-export command to capture the configuration you want to ship with your module:

lando drush az-core-config-export-single media.type.az_accessible_audio \
  > modules/custom/azqs_example/config/install/media.type.az_accessible_audio.yml

This command will:

  • Print the configuration as YAML to STDOUT.
  • Remove site-specific keys (uuid and _core).
  • Let you redirect (>) the output directly into your module’s config/install directory.

Notes

  • The file name must match the config object name (e.g., media.type.az_accessible_audio.yml).
  • Use this workflow for any config your custom module owns (views, content types, fields, media types, etc.).

2) Export config back into the Quickstart distribution

If you are contributing to the Quickstart project itself (e.g., updating config inside az_core or another bundled az_ module), use the distribution config export command:

lando drush az-core-distribution-config

This command will:

  • Compare active site configuration against the distribution’s shipped config.
  • Prompt you to update changed items into the owning module’s config/install directory.
  • Strip out site-specific keys (uuid, _core).
  • Apply special rules (e.g., role permission handling, metatag cleanup, merge behavior defined by the distribution).
  • Offer to export new dependencies if they are required.

Limit the scope to specific modules if needed:

lando drush az-core-distribution-config az_core,az_media

Reviewing your changes

For new config, quickly see what files need to be committed:

git status

For existing config, inspect the changes:

git diff

Finding config filenames

To export config, you need the machine name of the config object (e.g., views.view.az_newsletter, media.type.az_accessible_audio).

An easy way to find this is through the Configuration export UI:

  1. Go to /admin/config/development/configuration/single/export on your local Quickstart site.
  2. Choose the Configuration type (for example, “View” or “Media type”).
  3. Select the specific configuration item you are working on.
  4. At the bottom of the page, look for the Filename field — this shows you the config object name to use.

For example, exporting the “Remote audio” media type shows:

Filename: media.type.az_accessible_audio.yml

Use that value (without the .yml extension) in your Drush command:

lando drush az-core-config-export-single media.type.az_accessible_audio \
  > modules/custom/azqs_example/config/install/media.type.az_accessible_audio.yml

Finding hidden configuration

Sometimes you just can't figure out where the config you need is being set. A reliable approach is:

  1. Spin up a separate fresh Quickstart site, install the modules you need, and export the entire site's configuration.
  2. Export the config from the site where you made your change.
  3. Compare the two.

Export the entire site’s configuration via the UI at:

/admin/config/development/configuration/full/export

…or via the command line:

lando drush config:export

On a Mac, compare directories via CLI or a GUI:

diff -rq folder1 folder2

Xcode includes FileMerge, which can compare directories and files.