I built a tool to fix broken link previews because localhost testing was a nightmare

omer pakdil — Sun, 28 Dec 2025 15:07:58 +0000

We've all been there.

You spend weeks building a beautiful website. You deploy it on Vercel. You eagerly copy the link and paste it into your team's Slack channel or your family WhatsApp group to show it off.

And then... nothing.

Just a plain, ugly blue link. No image. No title. Maybe a random icon from your footer.

It looks broken. It feels unprofessional. And honestly, it hurts a little bit inside.

I spent way too much time debugging this recently. I realized that testing meta tags on localhost:3000 is impossible without tunneling tools like ngrok, and every platform (Twitter, WhatsApp, iMessage) has completely different, often undocumented, rules about image sizes and caching.

So, I decided to fix it once and for all. I built a dedicated debugging tool, but first, I want to share the Ultimate Cheat Sheet I wish I had when I started.

Here is exactly what you need to put in your <head> to make your links look premium on every platform.

The "Must-Have" Tags (Copy-Paste This)

If you ignore everything else, just add these 4 lines. This covers 90% of use cases.

<!-- 1. The Title (Keep it under 60 chars) -->
<meta property="og:title" content="My Awesome Project" />

<!-- 2. The Pitch (1-2 sentences) -->
<meta property="og:description" content="This is the coolest thing I've ever built." />

<!-- 3. The Image (CRITICAL!) -->
<meta property="og:image" content="https://mysite.com/og-image.png" />

<!-- 4. The Canonical URL -->
<meta property="og:url" content="https://mysite.com/" />

Why these matter:

og:title: This is your headline. If it's too long, it gets cut off. Keep it punchy.
og:description: Your elevator pitch. Don't stuff keywords here; write for humans.
og:image: The single most important factor for Click-Through Rate (CTR). A link with a big image gets clicked. A link without one gets ignored.

The "Gotchas" That Wasted My Time

Even with those tags, things still broke for me. Here is why detailed platform rules matter:

1. WhatsApp is Picky

WhatsApp is the worst offender. Many developers add a standard 1200x630px image and wonder why it doesn't show up.

The Problem: WhatsApp has a strict file size limit. If your image is > 300KB, it often just fails silently.
The Fix: You must compress your OG image heavily or provide a smaller, square fallback specifically for mobile apps.

2. iMessage Loves Icons

I was sending links via iMessage, and it kept ignoring my beautiful big banner.

The Problem: Unlike Facebook or Twitter, iMessage historically prioritizes the apple-touch-icon.
The Fix: Always add a high-res icon in your head.

<link rel="apple-touch-icon" href="/apple-touch-icon.png">

3. Twitter (X) Needs Extra Love

Twitter can use OG tags, but if you rely on the defaults, you get a tiny thumbnail on the left side of the tweet. It looks weak.

The Fix: Explicitly tell Twitter you want the "big card":

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:creator" content="@yourhandle" />

4. LinkedIn Caching

LinkedIn caches your link preview data aggressively—sometimes for up to 7 days.

The Nightmare: You deploy a fix for a typo in your title, but LinkedIn still shows the old one.
The Fix: You have to manually force a re-scrape using their "Post Inspector" tool, or change the OG image URL (e.g., add ?v=2) to trick the cache.

How I Solved It (The Lazy Way)

Debugging this manually is painful. You have to deploy to production, paste the link in a private Slack channel, see if it works, fix code, redeploy, repeat.

I built Katsau to solve this loop.

It's a suite of free debugging tools that emulate specific crawlers. Instead of a generic "preview", I built specific validators:

WhatsApp Previewer: Checks that sneaky 300KB limit for you.
Twitter Card Validator: Shows you exactly how the Summary Card renders.
Facebok Debugger: Simulates the standard OG scraper.

It's completely free to use for debugging. (I also built an API for developers who need to generate previews in their own apps, but the debug tools are open to everyone).

Wrapping Up

Don't let a fast deployment ruin your first impression.

Add the 4 essential tags.
Compress your images (seriously, check the file size).
Add the summary_large_image tag for Twitter.

If you found this helpful or if you try the tool, let me know what you think! I'm actively adding support for more platforms (Telegram is next on the roadmap).

Happy coding!

DEV Community: omer pakdil