social-metadata-hardening

name	social-metadata-hardening
description	Hardens Open Graph and Twitter Card tags so public URLs unfurl as rich cards on Facebook, LinkedIn, X, WhatsApp, Telegram, Slack, and Discord. Use when shared links show missing, stale, cropped, or broken previews, or when auditing og and twitter metadata before launch. Not for paid social ad creatives or sitemap-only SEO; never rely on client-side JS to inject tags crawlers must see.
version	1.0.1
category	seo
risk	safe
source	self
source_type	self
date_added	2026-05-31
tags	["seo","open-graph","twitter-card","social-sharing","og-image","nextjs","metadata"]
tools	["claude","cursor","gemini","claude-code"]

Social Metadata Hardening

Fix social sharing so every important URL unfurls as a rich card across all platforms. This skill covers OG tags, Twitter cards, absolute image URLs, metadataBase configuration, and cross-platform debugging.

When to Use

• Shared links show missing, stale, cropped, or incorrect previews on social or chat platforms.
• Auditing Open Graph, Twitter/X card, image URL, alt text, or metadataBase coverage in a web app.
• Pre-launch hardening when every public page needs predictable rich previews across LinkedIn, X, Facebook, WhatsApp, Slack, Discord, and Telegram.
• Tags were added client-side via JavaScript and crawlers cannot see them.

Prerequisites

• A deployed, publicly reachable URL (platform debuggers require live URLs).
• Node.js project using Next.js App Router (examples below); patterns adapt to other frameworks with static HTML head injection.
• PowerShell on Windows as primary shell. curl.exe (Windows 10+ built-in) or Invoke-WebRequest for verification.
• OG image asset hosted on HTTPS with no authentication required.

Procedure

Step 1 — Diagnose the current state

Check whether OG and Twitter tags exist in raw HTML (not JS-rendered):

# Windows PowerShell — fetch raw HTML and filter for social tags
(Invoke-WebRequest -Uri 'https://www.yourdomain.com/blog/my-post' -UseBasicParsing).Content `
  -split "`n" | Select-String -Pattern 'og:|twitter:'

# Alternative using curl.exe (ships with Windows 10+)
curl.exe -s https://www.yourdomain.com/blog/my-post | findstr /i "og: twitter:"

If tags do not appear in raw HTML, they are being injected by JavaScript and crawlers will not see them. Proceed to Step 2.

Step 2 — Create the shared metadata helper

Create lib/socialMetadata.js in your project. This helper guarantees absolute URLs, correct MIME types, and full OG + Twitter coverage:

// lib/socialMetadata.js
export function buildSocialMetadata({
  title,
  description,
  path,          // '/blog/my-post'
  image,         // '/images/og/my-post.jpg' or full URL
  imageAlt,
  imageWidth = ,
  imageHeight = ,
}) {
   baseUrl = process.. || ;

  
   imageUrl = image?.() ? image : ;
   pageUrl  = ;

  
   ext = imageUrl.().().();
   mimeMap = { : , : , : , :  };
   imageType = mimeMap[ext] || ;

   {
    title,
    description,
    : { : pageUrl },
    : {
      title,
      description,
      : pageUrl,
      : ,  
      : [{
        : imageUrl,
        : imageUrl,   
        : imageWidth,
        : imageHeight,
        : imageAlt || title,
        : imageType,
      }],
    },
    : {
      : ,  
      title,
      description,
      : [imageUrl],
    },
  };
}