Every config form covered so far assumes a saved value already exists — but on a freshly installed site, nothing has been saved yet. A config/install/*.yml file is what fills that gap: a starting value your module ships that gets copied into active config automatically the moment the module is installed, so the very first page load already has something sensible to show.
What you'll learn in this lesson
- Where default config files live and how their filename maps to a config object
- Exactly when Drupal copies this file into active storage
- Why the file's keys must match the schema's mapping exactly
- What happens if you skip shipping default config entirely
A real default config file
message: 'Awesome settings'Path: config/install/config_simple_example.settings.yml — a genuinely tiny file, one key, matching the one field this form manages.
How it works
The filename is the config object's name
The file config/install/config_simple_example.settings.yml corresponds directly to the config object named config_simple_example.settings — the exact same name declared in getEditableConfigNames() and in the schema file's top-level key from earlier lessons. Drupal derives the config object's name straight from the filename, minus the .yml extension.
When this file actually gets used
Drupal copies every file under a module's config/install/ directory into active configuration exactly once: the moment the module is installed. After that, this file is never consulted again — if a site administrator changes the message through the settings form, the file on disk in config/install/ stays untouched forever; only the live, active copy of the config changes. Reinstalling the module (uninstall, then install again) would reset the value back to this shipped default.
Keys must match the schema exactly
Recall the schema from an earlier lesson types message as text. This install file's one key, message, must match that mapping precisely — same key name, a value of the right shape. A mismatch here (a typo'd key, or a value of the wrong type) doesn't necessarily throw an immediate error, but it does mean the schema validator (and any strict config-checking in your CI pipeline) will flag it as invalid.
$config->get('message') call returns NULL instead of a helpful starting value — the textarea just shows empty, with no hint of what a reasonable value looks like.Quick check: if an administrator changes the message through the form, then later runs
drush config:export, which file reflects the new value — the one inconfig/install/, or a different one entirely? (Answer: a different one —config/install/only ever holds the shipped, install-time default.drush config:exportwrites the site's current active configuration into the project's configured config-sync directory, a completely separate location from any module'sconfig/install/folder.)
Key takeaways
- A module's default config lives in
config/install/<config_object_name>.yml, one file per config object. - Drupal copies this file into active configuration exactly once, at module install time — never again after that.
- The file's keys must exactly match the schema's
mappingfor the same config object. - Skipping default config isn't an error, but it leaves the first-run experience showing empty fields instead of sensible starting values.
Coming up next
You've now built a complete config settings form from scratch — form, schema, save, read, validate, and default values. Next, the tutorial shifts from simple settings config to entity forms: creating, editing, and validating full content entities, starting with "Creating Entity Add Forms."