Google Calendar Plugin for PayloadCMS

A comprehensive PayloadCMS plugin that provides two-way synchronization with Google Calendar, allowing users to manage calendar events directly within PayloadCMS with automatic sync to their Google Calendar accounts.

Features

🔄 Two-way synchronization between PayloadCMS and Google Calendar
🔐 OAuth2 authentication with Google Calendar API
📅 Multiple calendar support - sync with multiple Google Calendars
⚡ Real-time sync via webhooks (optional)
🕒 Scheduled sync with configurable intervals
🎯 Conflict resolution strategies (PayloadCMS wins, Google wins, newest wins)
📊 Sync logging and error tracking
🎨 Admin UI for managing calendar connections and settings
🔧 Flexible configuration options

Installation

npm install google-calendar-plugin
# or
yarn add google-calendar-plugin
# or
pnpm add google-calendar-plugin

Prerequisites

Google Cloud Project: Create a project in the Google Cloud Console
Enable Google Calendar API: Enable the Google Calendar API for your project
OAuth2 Credentials: Create OAuth2 credentials (Web application type)
Authorized Redirect URIs: Add your PayloadCMS domain + /api/google-calendar/callback

Configuration

1. Environment Variables

Add these environment variables to your .env file:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/google-calendar/callback

2. PayloadCMS Configuration

Add the plugin to your PayloadCMS config:

import { googleCalendarPlugin } from 'google-calendar-plugin'

export default buildConfig({
  // ... your existing config
  plugins: [
    googleCalendarPlugin({
      googleOAuth: {
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        redirectUri: process.env.GOOGLE_REDIRECT_URI!,
      },
      // Optional: Add calendar event relationship to existing collections
      collections: ['posts', 'events'], // Add googleCalendarEvent field to these collections
      // Optional: Configure sync interval (default: 15 minutes)
      syncInterval: 15,
      // Optional: Enable webhooks for real-time sync
      enableWebhooks: true,
      webhookDomain: 'https://yourdomain.com', // Required if enableWebhooks is true
    }),
  ],
})

Usage

1. Connect Google Calendar

Navigate to your PayloadCMS admin dashboard
You'll see a "Google Calendar Integration" section
Click "Connect Google Calendar"
Authorize the application in the popup window
Your calendars will be automatically synced

2. Manage Calendar Settings

Enable/Disable Sync: Toggle synchronization for individual calendars
Sync Direction: Choose between bidirectional, to Google only, or from Google only
Conflict Resolution: Set how conflicts are resolved when the same event is modified in both systems
Sync Interval: Configure how often automatic sync occurs

3. Create and Edit Events

Create events in the "Calendar Events" collection
Events are automatically synced to Google Calendar based on your settings
Edit events in PayloadCMS and changes sync to Google Calendar
Events created in Google Calendar sync back to PayloadCMS

4. Link Events to Other Collections

If you configured the collections option, you can link calendar events to other content:

// Example: Link a blog post to a calendar event
{
  title: "My Blog Post",
  content: "...",
  googleCalendarEvent: "event_id_here" // Relationship field added by plugin
}

API Endpoints

The plugin adds several API endpoints:

GET /api/google-calendar/auth - Get OAuth authorization URL
GET /api/google-calendar/callback - OAuth callback handler
GET /api/google-calendar/status - Check connection status
POST /api/google-calendar/sync/calendars - Manually sync calendars
POST /api/google-calendar/sync/events?calendarId=xxx - Sync events for specific calendar
POST /api/google-calendar/sync/all - Sync all calendars and events
POST /api/google-calendar/webhook - Webhook endpoint for real-time sync

Collections Added

The plugin adds these collections to your PayloadCMS:

Calendar Events

Slug: calendar-events
Purpose: Store calendar events with Google Calendar sync
Fields: Title, description, location, start/end times, attendees, recurrence, etc.

Google Calendars

Slug: google-calendars
Purpose: Store Google Calendar configurations and sync settings
Fields: Calendar name, colors, sync settings, last sync time, etc.

Google Auth Tokens

Slug: google-auth-tokens
Purpose: Store encrypted OAuth tokens for users
Fields: Access token, refresh token, expiration, scopes

Sync Logs

Slug: sync-logs
Purpose: Track synchronization operations and errors
Fields: Action type, status, error messages, timestamps

Calendar Sync Settings

Slug: calendar-sync-settings
Purpose: User-specific sync preferences
Fields: Sync direction, conflict resolution, intervals, notifications

Webhook Notifications

Slug: webhook-notifications
Purpose: Track Google Calendar webhook notifications
Fields: Notification data, processing status, timestamps

Configuration Options

interface GoogleCalendarPluginConfig {
  // Google OAuth2 configuration (required)
  googleOAuth?: {
    clientId: string
    clientSecret: string
    redirectUri: string
  }

  // Collections to add calendar event relationships to
  collections?: string[]

  // Sync interval in minutes (default: 15)
  syncInterval?: number

  // Enable webhook support for real-time sync
  enableWebhooks?: boolean

  // Webhook domain for Google Calendar notifications
  webhookDomain?: string

  // Disable the plugin
  disabled?: boolean
}

Webhook Setup (Optional)

For real-time synchronization, you can enable webhooks:

Set enableWebhooks: true in plugin config
Provide your public domain in webhookDomain
Ensure your server is accessible from the internet
Google will send notifications to /api/google-calendar/webhook

Security Considerations

OAuth tokens are stored encrypted in the database
All API endpoints require user authentication
Users can only access their own calendar data
Webhook endpoints validate Google's signatures
Sensitive token data is hidden in the admin UI

Troubleshooting

Common Issues

"OAuth configuration not provided"
- Ensure all Google OAuth environment variables are set
- Check that the plugin configuration includes googleOAuth settings
"Failed to connect Google Calendar"
- Verify your Google Cloud project has Calendar API enabled
- Check that OAuth credentials are correctly configured
- Ensure redirect URI matches exactly (including protocol and port)
"Sync not working"
- Check sync logs in the admin panel
- Verify calendar sync is enabled for specific calendars
- Check user sync settings and permissions
"Webhook notifications not received"
- Ensure your server is publicly accessible
- Check that webhookDomain is correctly configured
- Verify Google Calendar API quotas

Debug Mode

Enable debug logging by setting:

DEBUG=google-calendar-plugin:*

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

MIT License - see LICENSE file for details.

Support

For support, please:

Check the troubleshooting section above
Search existing GitHub issues
Create a new issue with detailed information about your problem

Changelog

v1.0.0

Initial release
Two-way Google Calendar synchronization
OAuth2 authentication
Real-time webhook support
Configurable sync settings
Admin UI for calendar management