Grab Meta Tags (Title/Description) from Sites with Node.js
While building Meta Preview Tool I needed a way to grab a page’s metadata from just a URL. It’s the same thing Discord, iMessage and Slack do when you paste a link and a preview card shows up.
In this post, I’ll show you how to get a page’s title, description, Open Graph image, site name and favicon from any URL with Node.js and Cheerio. There’s also a version for Cloudflare Workers with zero dependencies, and the packages worth using if you’d rather not write it yourself. Let’s get into it.
The Full Code
Since you’re likely here for the code, here it is. Install Cheerio first:
npm install cheerio
import * as cheerio from "cheerio";
export async function getMetadata(input) {
// Accept "example.com" as well as full URLs
const url = /^https?:\/\//i.test(input) ? input : `https://${input}`;
try {
const response = await fetch(url, {
redirect: "follow",
signal: AbortSignal.timeout(8000),
headers: {
// Some sites block requests with no browser-like user agent
"user-agent": "Mozilla/5.0 (compatible; MetaPreviewBot/1.0; +https://metapreviewtool.com)",
accept: "text/html,application/xhtml+xml",
},
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
if (!response.headers.get("content-type")?.includes("html")) throw new Error("Not an HTML page");
const $ = cheerio.load(await response.text());
const meta = (key) =>
$(`meta[property="${key}"]`).attr("content")?.trim() ||
$(`meta[name="${key}"]`).attr("content")?.trim() ||
"";
// Relative paths like "/og.png" are resolved against the final URL (after redirects)
const absolute = (path) => (path ? new URL(path, response.url).href : "");
return {
url: response.url,
title: meta("og:title") || $("title").first().text().trim(),
description: meta("og:description") || meta("description"),
image: absolute(meta("og:image") || meta("twitter:image")),
siteName: meta("og:site_name"),
favicon: absolute($('link[rel~="icon"]').attr("href") || "/favicon.ico"),
};
} catch (error) {
console.error(`Couldn't get metadata for ${url}:`, error.message);
return { url, title: "", description: "", image: "", siteName: "", favicon: "" };
}
}
Here’s the real output for getMetadata("github.com"):
{
"url": "https://github.com/",
"title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
"description": "Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
"image": "https://images.ctfassets.net/8aevphvgewt8/76epZKB2wF998m4e4bLLXn/c505f20b00ec70b88b1be5aec42c4be4/OG_image.jpg",
"siteName": "GitHub",
"favicon": "https://github.githubassets.com/favicons/favicon.png"
}
I tested this on Node 26 with Cheerio 1.2.0. It needs Node 18 or newer for the built-in fetch.
How It Works
Why it has to run on a server
You can’t fetch another site’s HTML from the browser. Cross-origin rules block the request unless that site allows it, and almost none do. So the fetch runs on your server (or a serverless function), and your frontend asks your server for the result.
Fetching the page
A few small details make this much more reliable than a bare fetch(url):
- Timeout:
AbortSignal.timeout(8000)gives up after 8 seconds, so one slow site can’t hang your app. - User agent: some sites return an error or an empty page when there’s no browser-like
user-agent. Naming your bot with a URL is the polite way to do it. - HTML only: if someone pastes a link to a PDF or an image, we stop instead of downloading and parsing it.
Reading the tags with Cheerio
Cheerio parses HTML on the server and lets you query it with jQuery-style selectors. The small meta() helper checks both property="..." and name="...", because sites mix them up all the time.
For each field there’s a fallback order:
- Title:
og:title, then the<title>tag. - Description:
og:description, then the regular meta description. - Image:
og:image, thentwitter:image. - Favicon: the
<link rel="icon">tag, then/favicon.ico.
One thing worth knowing: og:image and favicons are often relative paths like /images/og.png. new URL(path, response.url) turns them into full URLs, using the final address after any redirects.
Handling errors
Everything is wrapped in a try/catch. If the site is down, blocks you, or isn’t HTML, you get empty strings back instead of a crash. In your UI, show a plain link when the title comes back empty.
Using It as an API Endpoint
Here’s the function behind a Next.js API route, so your frontend can call it:
// app/api/meta/route.js
import { getMetadata } from "@/lib/getMetadata";
export async function GET(request) {
const url = new URL(request.url).searchParams.get("url");
if (!url) return Response.json({ error: "url parameter required" }, { status: 400 });
return Response.json(await getMetadata(url), {
// Cache each URL for a day so repeat previews are instant
headers: { "Cache-Control": "public, s-maxage=86400" },
});
}
Then from your frontend:
const res = await fetch(`/api/meta?url=${encodeURIComponent(inputUrl)}`);
const meta = await res.json();
One thing to know before you ship this: an endpoint that fetches any URL someone gives it can be pointed at your own internal network, like http://localhost or http://169.254.169.254. If it runs anywhere with private services, block private IP ranges before fetching, or use a package that does it for you (more below). Rate limiting the endpoint is a good idea too.
A Cloudflare Workers Version (No Dependencies)
If you’re on Cloudflare Workers, you don’t need Cheerio. Workers have HTMLRewriter built in, which streams through the page and calls your handlers as tags go by. This is what I’d use there:
// HTMLRewriter gives attribute values still HTML-encoded ("world's"), so decode them.
const ENTITIES = { amp: "&", quot: '"', lt: "<", gt: ">", apos: "'" };
const decode = (s) =>
s.replace(/&(#x[0-9a-f]+|#\d+|amp|quot|lt|gt|apos);/gi, (_, e) =>
e[0] === "#" ? String.fromCodePoint(e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10)) : ENTITIES[e.toLowerCase()],
);
export default {
async fetch(request) {
const target = new URL(request.url).searchParams.get("url");
if (!target) return Response.json({ error: "Add ?url=" }, { status: 400 });
const res = await fetch(target, { headers: { "user-agent": "Mozilla/5.0 (compatible; MetaPreviewBot/1.0)" } });
const tags = {};
let title = "";
await new HTMLRewriter()
.on("meta", {
element(el) {
const key = el.getAttribute("property") || el.getAttribute("name");
const content = el.getAttribute("content");
if (key && content && !(key in tags)) tags[key] = decode(content.trim());
},
})
.on("title", {
text(chunk) {
title += chunk.text;
},
})
.transform(res)
.arrayBuffer(); // read the body so the handlers run
const image = tags["og:image"] || tags["twitter:image"];
return Response.json({
title: tags["og:title"] || decode(title.trim()),
description: tags["og:description"] || tags.description || "",
image: image ? new URL(image, res.url).href : "",
});
},
};
I ran this in Miniflare (the local Workers runtime) against GitHub and this blog, and it returns the same title, description and image as the Cheerio version. The decode step matters: without it, GitHub’s description comes back as the world's most widely adopted.
Or Use a Package
If you’d rather not maintain this yourself, these are the ones worth looking at:
- linkpeek: the newest and fastest of the bunch, with SSRF protection built in.
const result = await preview("https://github.com")gives youtitle,description,image,siteNameandfavicon. I tried version 3.2.0 and it returned the same data as my function above. - open-graph-scraper: the long-standing popular choice, with Open Graph, Twitter Card and other metadata. It’s heavier than linkpeek.
- url-metadata: works in Node and the browser, and can parse HTML you already fetched.
For a link preview feature in your own app, the function above is usually enough. For anything that fetches URLs from the public at scale, a maintained package with SSRF protection saves you some headaches.
When This Won’t Work
- JavaScript-rendered sites: Cheerio and HTMLRewriter only see the HTML the server sends. If a site sets its title and meta tags with React or Vue after the page loads, you’ll get empty strings. Most sites render meta tags on the server for exactly this reason (social networks don’t run JavaScript either), but for the ones that don’t, you’d need a headless browser like Puppeteer.
- Sites with bot protection: some sites block automated requests no matter what user agent you send. For a personal tool that’s rare. For high volume, you’d need a scraping service.
This has worked well in production for Meta Preview Tool. If you want to see how a link will look when it’s shared, you can test any URL there.
Slap a sticker on this post
Comments
Loading comments…