Payload-bidirectional-relationships-plugin NPM

payload-bidirectional-relationships-plugin

plugin for Payload CMS, which enables bidirectional relationships

:boom: :boom: :boom: works :100: with PayloadCMS version :two: and :three: :boom: :boom: :boom:

:bangbang: currently only works with MongoDB :bangbang:

!NOTE
You are currently in the v3 branch!

Go to main branch

Go to v2 branch

What this is for

You have collections that are referencing each other in a bidirectional MxN way.
Those relationships have properties on their own, but you don't want them to have their own collection - instead you would like those properties to be embedded within the relationship field and synchronized between both related collections.

Example use case

Collection A: Projects (e.g. Open Source Projects)
Collection B: Persons (e.g. Developers)
Relation between A and B: Participation (i.e.: persons could participate in some way in a project - projects have participants)
Each relation (participation) has meta data (e.g. type of participation: contributor, moderator, core, owner, guest, etc.)
you want those information to be embedded in both collections and automatically synced (no third collection for the relation)

How the plugin works

you define the relationships
this gives you the two anchors
you place those anchors at the desired place in the collections
you add the plugin to your payload config with those relationships as parameters
the plugin handles automatically all synchronization hooks

Install

pnpm add payload-bidirectional-relationships-plugin@0.4.5-v3

!WARNING
Be aware to install only that version of this plugin which is compatible with the PayloadCMS version you are using! So if you are using PayloadCMS v2, there should be a '-v2' at the end instead of a '-v3' and vice versa. In the future, when this plugin becomes stable, there will be 2.x.x and 3.x.x versions.

Usage

define relationships

import {biDirectionalRelationship} from 'payload-bidirectional-relationships-plugin'

export const relationAB = biDirectionalRelationship({
    vertexA: {
        anchor: 'collectionA.listA.fieldA',
        // Options for the ArrayField 'listA'
        listOptions: {
            label: 'Relations to a document of Type B',
            labels: {
                singular: 'Relation to a document of Type B',
                plural: 'Relations to a document of Type B'
            }
        },
        // Options for the RelationshipField 'fieldA'
        fieldOptions: {
            label: 'Reference to a document of Type B'
        }
    },
    vertexB: {
        anchor: 'collectionB.listB.fieldB',
        listOptions: {
            label: 'Relations to a document of Type A',
            labels: {
                singular: 'Relation to a document of Type A',
                plural: 'Relations to a document of Type A'
            }
        },
        fieldOptions: {
            label: 'Reference to a document of Type A'
        }
    },
    /*
        array of fields that will be display beneath each relation field;
        each field is "part" of the relationship and describes it
    */
    relationMeta: [
        {
            name: 'relationMeta',
            type: 'text'
        }
    ]
})

add anchors to the collection configs at the desired place:

import {CollectionConfig} from 'payload/types'
import {relationAB} from './relationships'

export const CollectionA: CollectionConfig = {
    slug: 'collectionA',
    labels: {
        singular: 'Document of Type A',
        plural: 'Documents of Type A',
    },
    admin: {
        useAsTitle: 'name',
    },
    fields: [
        {
            name: 'name',
            type: 'text'
        },
        relationAB.anchors.collectionA
    ],
}

export const CollectionB: CollectionConfig = {
    slug: 'collectionB',
    labels: {
        singular: 'Document of Type B',
        plural: 'Documents of Type B',
    },
    admin: {
        useAsTitle: 'name',
    },
    fields: [
        {
            name: 'name',
            type: 'text'
        },
        relationAB.anchors.collectionB
    ],
}

add hooks by using the plugin and referencing all relationships:

import {buildConfig} from 'payload/config'
import {relationAB, /*...*/} from './relationships'

export default buildConfig({
    //...,
    plugins: [
        //...,
        biDirectionalRelationships([relationAB /*, ...*/])
    ]
})