[finalburn]

Fixes #2754.

What

config.view_component, config.view_component.previews and config.view_component.generate were plain ActiveSupport::OrderedOptions, so setting any key worked and nothing read it. Options renamed or removed in 4.0 (preview_controller, test_controller, …) and typos (instrumentaton_enabled) were silently ignored.

They're now ViewComponent::Config::Options, a subclass that raises ViewComponent::UnknownConfigOptionError when an unknown option is set, at the line in the app's config that sets it:

`config.view_component.preview_controller` was renamed to `config.view_component.previews.controller` in ViewComponent 4.0.
`config.view_component.test_controller` was removed in ViewComponent 4.0. Use the `vc_test_controller_class` test helper instead.
`config.view_component.instrumentaton_enabled` isn't a ViewComponent configuration option. Valid options are: generate, previews, instrumentation_enabled.

The 4.0 renames and removals live in frozen constants on ViewComponent::Config (RENAMED_OPTIONS, RENAMED_GENERATE_OPTIONS, REMOVED_OPTIONS). Reading an unknown option still returns nil, so gems that check old keys don't break at boot.

Future renames

Options takes a deprecated: map so a future rename can warn before it raises:

1. In a minor release, add the new option and map the old name to its path in deprecated. Setting or reading the old name emits a ViewComponent::Deprecation warning and uses the new option.
2. In the next major, move the old name to the renamed/removed constants so that setting it raises.

deprecated is empty for now. A test fails once the major version reaches DEPRECATION_HORIZON while any deprecated options remain.

Things to note

• Apps that still set dead keys will now fail to boot until they remove them. That's the intent, but it's a behaviour change in a minor release.

Testing

New tests in test/sandbox/test/config_test.rb. I couldn't run the full suite locally: bundle install fails because rubydex and cruise need a Rust toolchain. Instead I ran config_test.rb against the installed ActiveSupport with a stub test_helper, which covers all the new tests and test_all_methods_are_documented, and standardrb lib test passes. The full suite will run in CI.

🤖 Generated with Claude Code

[czj]

Thanks for picking this up so quickly, @finalburn! I ran the full suite on this branch (Ruby 4.0.9, Rails 8.1): all green, apart from one flaky system test that passes on its own.

On the "overcomplicated" part, two ideas to slim it down:

• Drop the deprecated: mechanism for now. Nothing uses it yet, and it's about half the diff. It can come with the next rename that needs it.
• Merge RENAMED_GENERATE_OPTIONS into RENAMED_OPTIONS. It only repeats component_parent_class.

One small gap: config.view_component.previews = ActiveSupport::OrderedOptions.new replaces the strict options with a plain one, so typos under it go unnoticed again. Probably rare, maybe worth a guard.

Happy to help if you'd like!

[Copilot]

🟡 Changes recommended

Inherited Hash mutation methods bypass validation and namespace wrapping, allowing removed keys and unvalidated nested configuration to be accepted silently.

3 open issues

• Validate inherited Hash mutation methods · New
• Restrict generate option rename mapping · New
• Update generator parent_class documentation path · New

What changed in this PR

This PR adds fail-fast validation to ViewComponent’s Rails configuration, helping applications catch obsolete settings and typos instead of silently ignoring them.

Changes:

• Introduces validated configuration options with migration guidance for settings renamed or removed in 4.0.
• Preserves validation when replacing nested configuration with hashes, while keeping unknown reads non-raising.
• Adds regression tests and documents the behavior change.

File	Description
test/​sandbox/​test/​config_test.rb	Tests valid settings, rejected keys, unknown reads, and nested replacements.
lib/​view_component/​errors.rb	Adds configuration errors with replacement guidance and valid-option lists.
lib/​view_component/​config.rb	Introduces validated options and mappings for obsolete settings.
docs/​CHANGELOG.md	Documents stricter configuration validation.

_{Review effort: Max}

[finalburn]

Thanks for wrapping this one up @joelhawksley!