💻OpenGraph Metadata Guide

Overview

OpenGraph metadata helps control how your pages appear when shared on social media platforms like Facebook, Twitter, LinkedIn, and others. Different page types support different metadata fields, and using the correct type is crucial for proper display.

OpenGraph Types and Their Fields

website (Default Type)

The most basic type, suitable for homepages, landing pages, and general web pages.

Supported Fields:

• title - The title of your page
• description - A brief description of the page content
• url - The canonical URL of the page
• siteName - The name of your overall site
• images - Array of images to display
• locale - The locale of the content (e.g., 'en_US')

Example Implementation:

export const metadata: Metadata = {
  openGraph: {
    title: 'Projected Cash Flow',
    description: 'Visualize your financial future',
    type: 'website',
    url: 'https://projectedcashflow.app',
    siteName: 'Projected Cash Flow',
    images: [{
      url: '/og-image.png',
      width: 1200,
      height: 630,
    }],
    locale: 'en_US',
  },
};

article

Use for blog posts, documentation pages, news articles, or any time-sensitive content.

Supported Fields: All website fields PLUS:

• publishedTime - ISO 8601 datetime when article was published
• modifiedTime - ISO 8601 datetime when article was last modified
• expirationTime - When the article is out of date
• authors - Array of article authors
• section - High-level section name (e.g., 'Technology')
• tags - Array of relevant tags

Example Implementation:

export const metadata: Metadata = {
  openGraph: {
    title: post.title,
    description: post.excerpt,
    type: 'article',
    publishedTime: post.publishedDate,
    modifiedTime: post.lastUpdated,
    authors: [post.author],
    section: post.category,
    tags: post.tags,
  },
};

Other Common Types

profile

For user profiles or author pages:

• Adds: firstName, lastName, username, gender

book

For book-related content:

• Adds: authors, isbn, releaseDate, tags

video.movie / video.episode

For video content:

• Adds: actors, directors, writers, duration, releaseDate

music.song / music.album

For music content:

• Adds: duration, album, musicians

Best Practices

1. Choose the Right Type

• Homepage, pricing, contact pages → website
• Blog posts, docs, news → article
• User profiles → profile
• Product pages → product (if e-commerce)

2. Handle Nullable Dates

When using article type with Keystatic or CMS content:

openGraph: {
  type: 'article',
  publishedTime: page.publishedDate || undefined,
  modifiedTime: page.lastUpdated || undefined,
}

3. Image Requirements

• Recommended size: 1200x630px
• Minimum size: 600x315px
• Aspect ratio: 1.91:1
• Format: PNG or JPG
• File size: Under 8MB

4. Testing Your Metadata

Use these tools to preview how your content will appear:

• Facebook Sharing Debugger
• Twitter Card Validator
• LinkedIn Post Inspector

Common Mistakes to Avoid

1. Using publishedTime with website type

// ❌ Wrong - publishedTime is ignored for website type
openGraph: {
  type: 'website',
  publishedTime: '2025-01-01', // This won't work!
}

// ✅ Correct - use article type for dated content
openGraph: {
  type: 'article',
  publishedTime: '2025-01-01',
}

2. Missing Required Fields

Always include at minimum:

• title
• description
• type
• url (highly recommended)
• images (highly recommended)

3. Incorrect Date Formats

Dates must be in ISO 8601 format:

// ❌ Wrong
publishedTime: 'January 1, 2025'

// ✅ Correct
publishedTime: '2025-01-01T00:00:00Z'

Implementation Example

Here's a complete example for a blog post page:

import { Metadata } from 'next';

export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await getPost(params.slug);
  
  return {
    title: `${post.title} | My Blog`,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      type: 'article',
      publishedTime: post.publishedDate,
      modifiedTime: post.updatedAt,
      authors: [post.author.name],
      section: post.category,
      tags: post.tags,
      images: [
        {
          url: post.featuredImage || '/default-og-image.png',
          width: 1200,
          height: 630,
          alt: post.title,
        }
      ],
      siteName: 'My Blog',
      locale: 'en_US',
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.excerpt,
      images: [post.featuredImage || '/default-og-image.png'],
    },
  };
}

Debugging Tips

1. Check the rendered HTML - View page source and look for <meta property="og:*"> tags
2. Use browser extensions - Install OpenGraph preview extensions
3. Clear social media cache - Platforms cache OpenGraph data; use their debugging tools to refresh
4. Validate your markup - Use online validators to check for errors

Summary

Proper OpenGraph implementation improves how your content appears across social media platforms. Remember to:

• Use the appropriate type for your content
• Include all required fields
• Test your implementation with platform-specific tools
• Keep dates in ISO 8601 format
• Optimize images for social sharing

By following these guidelines, your content will look professional and engaging when shared on social media platforms.