Extensions in Directus are where the 'CMS becomes a product': validations, transformations, and automations happen alongside the data lifecycle.
Use this skill to define boundaries: what stays in the schema/policies and what becomes an extension. A bad extension becomes an operational risk.
Decide where to implement
- Schema/fields/constraints: structural validations, types, limits.
- Auth/permissions/policies: who sees/edits what.
- Hooks: immediate and consistent side effects on write.
- Flows: longer automations, triggered by events, with retries/control.
- Custom endpoints: when the API needs its own contract.
Hooks
Rules:
- Idempotency: the same write must not duplicate effects.
- Do not do heavy work in the request path; if needed, use 'enqueue'/fast side effect.
- Validate input and failures with useful messages for the user when it makes sense.
- Always handle errors (do not swallow them): a failure must return a coherent status.
Flows
Rules:
- Define the trigger clearly (event, collection, status).
- Generate a 'correlation id' to track logs and retries.
- Retry only for transient errors and with backoff.
- Protect against duplicate events (eventual delivery).
Transformations and normalization
- Transformations that must be deterministic go in hooks.
- Transformations that vary by context (e.g., tenant) must derive from item data + config.
- Do not store secrets in an extension. Use env/secret management from your setup.
Operation and security
- Log only what is necessary; avoid full PII.
- Test scenarios:
- simple update
- creation with required fields
- failure at an external step
- retries (duplication)
- Respect policies: an extension does not 'escape' authz.
Integration with the rest
- Data:
directus-data-modeling - Security:
directus-auth-permissions - Consumption in the app:
directus-integration - Files/Assets:
directus-files
Completion criteria
- Hooks/flows are deterministic and idempotent
- Failures return coherent behavior and do not leave inconsistent data
- Traceable logs and no leakage of secrets/PII