Payload Dub integration

The Payload Dub Integration Plugin automates the creation and maintenance of short links and tag metadata between Payload CMS and Dub. It introduces two collections, system hooks, and synchronisation logic that ensure each published document receives a canonical short link and consistent tag data.

Planned updates will expand the plugin with link analytics, in-panel management tools, and optional UTM parameter support for campaign tracking.

Dub

Dub.co is a professional link management platform designed for marketing and product teams. It provides tools for creating branded short links, organising them into folders, applying campaign tags, and monitoring link performance through real-time analytics.

Dub’s API enables seamless programmatic control over links and tags, making it an ideal companion for CMS workflows. By integrating Dub with Payload, users gain centralised governance over links, consistent tagging, and potential access to performance metrics without leaving their content environment.

Functions

On installation, the plugin registers two dedicated collections:

• dubLinks: Stores each link’s externalId, shortLink, relation to source content, and tag associations.
• dubTags: Stores tagID, name, and color, mirroring tag records from Dub.

If a configured collection does not include a dubTags relationship field, the plugin injects one automatically. It also attaches an afterChange hook to monitored collections that triggers when a document is created or updated with a published status, ensuring every live record receives a valid short link and synchronised tag data.

Management

The plugin manages tag consistency through beforeChange and afterDelete hooks that mirror tag creation, updates, and removals between Payload and Dub.

In Pro mode, the plugin supports Dub folder integration by creating or locating a corresponding folder and storing its folderId for improved organisation. Tenant mapping is supported via a user_ prefix for normalised tenant identifiers.

Installation

Install the plugin from npm or pnpm

pnpm install @rubixstudios/payload-dub

Then integrate it in your Payload configuration file:

// payload.config.ts
import { buildConfig } from 'payload/config'
import { payloadDub } from '@rubixstudios/payload-dub'
 
export default buildConfig({
  plugins: [
    payloadDub({
      collections: [
        { docs: 'posts', slugOverride: 'post' }, // Custom slug for Dub folder and shortlinks
        { docs: 'insights', slugOverride: 'insight' }, // Custom slug only
        { docs: 'news' }, // Default behaviour
      ],
      dubApiKey: process.env.DUB_API_KEY || '',
      siteUrl: process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000',
      domain: 'mycustomdomain.com', // Optional: custom Dub domain
      tenantId: '12345', // Optional: tenant identifier for Dub workspace
      isPro: false, // Optional: enables Dub Pro features
 
      // Optional overrides for Dub collections
      dubCollection: {
        overrides: {
          access: {
            read: ({ req }) => !!req.user,
            create: ({ req }) => !!req.user,
          },
          admin: {
            group: 'Marketing',
            defaultColumns: ['shortLink', 'externalId'],
          },
        },
      },
      dubTagCollection: {
        overrides: {
          access: {
            read: ({ req }) => !!req.user,
          },
          admin: {
            group: 'Marketing',
            defaultColumns: ['name', 'color'],
          },
        },
      },
    }),
  ],
})

After setup, publishing any document in a configured collection automatically generates or updates a short link in Dub and stores it in Payload’s dubLinks collection.

Planned

Upcoming support will integrate Dub’s analytics API, enabling retrieval of metrics such as click counts and unique visitors directly into the dubLinks collection. This will allow content teams to review link performance from within Payload.

Future releases will provide UTM parameter configuration at either collection or document level. During link generation, standard parameters (utm_source, utm_medium, utm_campaign) or custom values will be appended automatically, supporting structured campaign tracking.

Audience

The plugin is designed for Payload CMS users who require automated short-link generation and centralised tag control for published content. It suits editorial, marketing, and multi-tenant teams seeking consistent link governance, with planned extensions to deliver analytics visibility and campaign-level insights.

The Payload Dub Integration Plugin offers reliable automation for link and tag synchronisation between Payload CMS and Dub. With planned analytics, and UTM-tracking updates, it will evolve into a comprehensive publishing and measurement tool for content teams.

Repository

https://github.com/rubix-studios-pty-ltd/payload-dub

https://www.npmjs.com/package/@rubixstudios/payload-dub