payload-plugin-social-media

Social media plugin for Payload CMS 3. Automatically post to Bluesky, Mastodon, and Reddit when documents are published.

Features

• Multi-platform posting (Bluesky, Mastodon, Reddit)
• Automatic posting on document publish via background jobs
• Manual sharing with admin UI share button
• Template system with per-platform character limits
• Engagement tracking (likes, reposts, replies, comments)
• URL shortener with click and referrer analytics
• Encrypted token storage (AES-256-GCM)
• Admin dashboard widget and account management UI

Installation

pnpm add payload-plugin-social-media

Usage

// payload.config.ts
import { buildConfig } from 'payload';
import { socialMediaPlugin } from 'payload-plugin-social-media';

export default buildConfig({
  // ...
  plugins: [
    socialMediaPlugin({
      collections: ['posts', 'articles'],
      encryptionKey: process.env.SOCIAL_ENCRYPTION_KEY!, // 32+ characters
      baseUrl: process.env.PAYLOAD_PUBLIC_SERVER_URL!,
      platforms: ['bluesky', 'mastodon', 'reddit'],

      // Optional: Bluesky config (uses app passwords, not OAuth)
      bluesky: {
        service: 'https://bsky.social', // default
      },

      // Optional: Mastodon OAuth credentials per instance
      mastodon: {
        instances: {
          'mastodon.social': {
            clientId: process.env.MASTODON_CLIENT_ID!,
            clientSecret: process.env.MASTODON_CLIENT_SECRET!,
          },
        },
      },

      // Optional: Reddit OAuth credentials
      reddit: {
        clientId: process.env.REDDIT_CLIENT_ID!,
        clientSecret: process.env.REDDIT_CLIENT_SECRET!,
        userAgent: 'myapp/1.0',
      },
    }),
  ],
});

Configuration

| Option | Type | Required | Default | Description | |---|---|---|---|---| | collections | string[] | Yes | - | Collection slugs to enable social posting on | | encryptionKey | string | Yes | - | 32+ character key for encrypting stored tokens | | baseUrl | string | Yes | - | Base URL for short links and OAuth callbacks | | platforms | Platform[] | Yes | - | 'bluesky', 'mastodon', 'reddit' | | slugPrefix | string | No | 'social' | Prefix for plugin-created collections | | access | object | No | - | Access control overrides for plugin collections | | bluesky | object | No | - | Bluesky service URL override | | mastodon | object | No | - | Per-instance OAuth client credentials | | reddit | object | No | - | Reddit OAuth credentials and user agent |

Collections

The plugin creates five collections (prefixed with slugPrefix, default social):

| Collection | Description | |---|---| | social-accounts | Connected platform accounts with encrypted tokens | | social-templates | Post templates per platform and collection | | social-posts | Queued and published social posts | | social-interactions | Engagement metrics and comments | | social-links | Short links with click tracking |

Templates

Templates use {{variable}} syntax with these available variables:

| Variable | Description | |---|---| | {{title}} | Document title | | {{excerpt}} | Document excerpt | | {{url}} | Full document URL | | {{shortUrl}} | Shortened URL | | {{author}} | Document author | | {{collection}} | Collection name |

Content is automatically truncated to platform limits (Bluesky: 300, Mastodon: 500, Reddit: 40,000 characters).

Client Components

Import admin UI components from the /client subpath:

import {
  ShareButton,
  PostStatusField,
  EngagementPanel,
  DashboardWidget,
  ConnectAccountView,
  TemplateEditorView,
} from 'payload-plugin-social-media/client';

License

Elastic License 2.0 (ELv2). Free to use, modify, and distribute. Cannot be offered as a hosted/managed service.