Link Preview Meta

The failures, all mundane and all silent

A relative og:image. It renders fine in your page and fetches nothing for a crawler, which has no base URL to resolve it against. This is the single most common broken card.

Missing width and height. Several platforms will not render a card until they have fetched and measured the image. Supply the dimensions and it renders immediately; omit them and the first share of a new link often shows nothing — which is the share that matters.

An http image on an https page. Silently dropped by most crawlers.

Wrong aspect ratio for a large card. Not rejected — cropped, usually through the middle of whatever you wanted seen.

One set of tags for every page. A root layout that sets og:title once means every article shares as the site name. Each page looks correct in isolation; the problem is visible only by comparing two, which is exactly what a human reviewer never does. detectSharedDefaults compares them for you.

Truncation. Platforms cut at their own limits, mid-word, invisibly. fitToLimit cuts at a word boundary so the ellipsis lands where you chose — the difference between *"How we cut our build time by…" and "How we cut our build time b"*.

It reports everything at once

A card is judged as a whole: a correct title with a broken image is still a broken card. Returning the first problem means fixing them one deploy at a time, each round requiring you to ask someone else to paste your link into a channel and describe what they see.

Errors and warnings are different

Errors break the card — no title, no image, a relative image URL, a non-absolute og:url. Warnings degrade it: truncation, a small image, a cropped ratio, missing alt text. metaIsRenderable gates on errors only, so a warning never blocks a deploy.

Missing og:image:alt is a warning rather than a nicety — the card is unreadable to anyone using a screen reader.

What this does NOT do

No HTML parsing and no fetching: you pass the values you are about to render, so it runs in a unit test rather than against a deployed page. It cannot tell you whether the image URL resolves — only that it is shaped so a crawler could try.

No sitemap, robots, canonical-tag or structured-data handling. No preview rendering, and no platform-specific validation beyond the shared limits — the numbers here are the shortest in common use, so passing them is safe everywhere rather than optimal anywhere.

Verified

18 tests: relative and http images refused, missing dimensions warned with the first-share consequence, undersized images, large-card ratio cropping, missing alt, missing and over-long titles, empty strings treated as missing, shared titles and shared og:url across pages, no false positive on a single page or on genuinely differing pages, all problems returned at once, and word-boundary trimming.

Not covered: no test fetches a real image or asks a real platform how it would render. The limits are documented values, not measurements.