hook_theme_suggestions_HOOK vs. hook_theme_suggestions_HOOK_alter

Question

Let's say some people are working on a contrib module (link) to provide some obvious template suggestions which are not covered by the default Twig Template naming conventions. View mode for fields, region for blocks etc.

Out of habit I'd use hook_theme_suggestions_HOOK_alter. I simply add my suggestions following some logic, done.

This hook allows any module or theme to provide alternative theme function or template name suggestions and reorder or remove suggestions provided by hook_theme_suggestions_HOOK() or by earlier invocations of this hook.

Then I see there's hook_theme_suggestions_HOOK which more or less does the same except for reordering or removing suggestions. But basically looking at its description it does exactly what that contrib module is supposed to do.

This hook allows modules to provide alternative theme function or template name suggestions.

And now I'm wondering which one of these hooks should be used at best? Is it totally up to us? Do there arise any disadvantages of using the *_alter hook? Do we better use the mere suggestion *_HOOK to allow other modules to intervene later in the process?

Answer 1

The linked module should try to add suggestions in hook_theme_suggestions_HOOK as long as it doesn't depend itself on existing suggestions, so that other modules still have the option to override these suggestions in an alter hook.

Hooks don't have priorities, which having two hooks, one main and one alter hook, is trying to compensate. This is like a priority system with only two levels. If you add something on the second level there is no third level for other modules, unless they resort to unusual solutions like module weights.