Collection References

About

Payload lets a relationship or upload field keep pointing at a document that no longer exists. This plugin closes that gap. At config initialization it walks every targeted collection's field tree (including groups, tabs, and arrays) and records each `relationship` and `upload` field by its dot-notation path, then injects a `beforeDelete` hook on every collection that something else references. When a document is deleted, the hook queries all referencing collections and applies one of two strategies per field: `delete` cascade-removes the referencing documents (and re-triggers their own `beforeDelete` hooks recursively) or `unlink` sets the field to `null` or a custom `unlinkValue` while preserving the document. Auto-discovery defaults to `delete`; explicit declarations override the strategy per field. Configuration is small. Call `collectionReferencesPlugin()` with no arguments to apply to every collection, or pass `collections` for an allowlist, `exclude` for a blocklist, and `declarations` for per-field overrides with nested paths like `seo.ogImage`. A `disabled` flag turns the plugin into a no-op, useful for test environments. Circular references between collections are tracked through `req.context` to prevent infinite loops. For projects that want finer control, the core API is exported separately: `withCollectionReferences` wraps a single collection config, `finalizeCollectionReferences` resolves the set, and helpers like `getReferencesPointingTo`, `buildWhereForReferences`, and `groupReferencesByCollection` expose the internals. The plugin targets Payload `^3.84.1` and is explicitly experimental: collection schemas and behavior may change between releases, so pin versions deliberately.

Package info

Package name

@lizardglobal/payload-collection-references

Latest version

1.0.1

Unpacked size

95 kB

License

MIT

Last publish

Aug 3, 2026