Summary

Allow explicit control over the execution order of custom hooks/extensions listening to the same event in Directus.

Basic Example

Suppose you have two hooks: one called hook-virus-scanner that scans uploaded files for viruses, and another called hook-file-processor that processes files after upload. With this feature, you could explicitly specify that hook-virus-scanner should always run before hook-file-processor, ensuring files are scanned before any processing occurs.

Motivation

Currently, the execution order of hooks is determined by their names, which is not explicit or reliable. This limits modularity and maintainability, as developers must use naming conventions to control order. Explicit ordering would enable smaller, focused extensions and allow instance-level customization, supporting more complex and modular workflows.

Detailed Design

• Introduce an order property for hook definitions, or a global configuration mapping events to hook execution order
• When multiple hooks listen to the same event, Directus will execute them in the specified order
• If no order is specified, fallback to current behavior (alphabetical by name)
• Instance-level configuration can override default order, allowing different environments to customize hook precedence

Requirements List

Must Have:

• Allow explicit ordering of hooks per event
• Support both per-hook and global configuration
• Maintain backward compatibility

Should Have:

• Allow instance-level overrides
• Provide clear error messages for conflicting or missing order definitions

Could Have:

• Support dynamic reordering at runtime

Won't Have:

• Change the default behavior for projects not using this feature

Drawbacks

• Adds complexity to hook configuration
• Potential for misconfiguration if orders conflict or are not unique
• May require additional documentation and migration guidance

Alternatives

• Continue using naming conventions to control order (current workaround)
• Implement a plugin system with explicit dependencies between hooks
• Do nothing; accept the current limitations

Adoption Strategy

• This is a non-breaking, opt-in feature
• Existing projects will continue to work as before unless they specify hook order
• Migration involves adding the order property or global config for projects needing explicit control
• Documentation and examples should be provided to guide adoption

Unresolved Questions

No response