payload-bidirectional-relationships-plugin

plugin for Payload CMS, which enables bidirectional relationships

Caution

With the new Join Field and the ability to hide certain collections from the Admin Dashboard ({..., admin:{hidden:true},...}) there is no longer a need for this plugin. I will no longer maintain it.

If you want me to continue, you can open up a discussion.

Thank you, everybody, for the stars! This was my first open source project. ❤️

Note

You are currently in the main branch!

Go to v2 branch

Go to v3 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

PayloadCMS v2:

pnpm add payload-bidirectional-relationships-plugin@0.3.0-v2

PayloadCMS v3:

pnpm add payload-bidirectional-relationships-plugin@0.3.0-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 v3, there should be a '-v3' at the end instead of a '-v2' 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 /*, ...*/])
    ]
})

Possible future features

• possibilty to define sync and deletion rules
• allow for 1x1 relationships (without ArrayField)
• allow for polydirectional relationships (more than two anchors)

What is planned in the near future

• when Payload v3 becomes stable: release of 2.0.0 (stable) and 3.0.0 (stable)
• maybe a PR for the payload monorepo?