linkpeek

Lightweight, safe-by-default link preview and URL metadata extraction for Node.js, Bun, Deno, and fetch-based edge runtimes. One runtime dependency.

A modern, lightweight alternative to link-preview-js and open-graph-scraper: one focused TypeScript API that turns any URL into Open Graph, Twitter Card, and JSON-LD preview metadata, with SSRF-safe fetching built in.

import { preview } from "linkpeek";

const result = await preview("https://www.youtube.com/watch?v=dQw4w9WgXcQ");

result.title;       // "Rick Astley - Never Gonna Give You Up"
result.image;       // "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
result.siteName;    // "YouTube"
result.favicon;     // "https://www.youtube.com/favicon.ico"
result.description; // "The official video for \"Never Gonna Give You Up\"..."

Install

npm install linkpeek

Runtime support:

| Runtime | Support | | --- | --- | | Node.js | 22+ | | Bun | Current stable | | Deno | import { preview } from "npm:linkpeek" | | Edge runtimes | Fetch-compatible runtimes such as Cloudflare Workers and Vercel Edge |

CI tests Node 22, Node 24, Node 26, Bun, and Deno.

Why linkpeek

linkpeek focuses on server-side preview cards: fetch a URL, read only enough HTML for useful metadata, and return a stable result shape without a DOM-heavy scraper stack. It is a small metadata extractor for applications that already have a URL and need a safe preview-card result.

• 1 runtime dependency: htmlparser2
• Streaming fetch with a strict byte limit
• Head-first SAX parsing with no DOM construction
• Safe defaults: private/internal IP targets blocked by default
• Dual ESM/CJS package output with TypeScript declarations for both module systems

linkpeek is intended for server-side use. Put it behind an API route and return only the metadata your client needs.

Use cases

• Chat and messaging apps that need Slack-style link cards
• Social feeds, bookmarking tools, and link-curation products
• Newsletter and CMS workflows that preview outbound links
• AI agents or RAG tools that unfurl URLs before summarizing or ranking them

When to use linkpeek

Use linkpeek when you already have a URL and need a small, safe preview-card result for a server-side or edge-runtime app. It is designed for Open Graph, Twitter Card, JSON-LD, canonical URL, favicon, media URL, and oEmbed discovery.

Use a broader scraper package when you need article text extraction, provider-specific scraping rules, text-to-first-URL parsing, or automatic fetching of oEmbed payloads.

Quick comparison:

| Package | Good fit | Tradeoff vs linkpeek | | --- | --- | --- | | link-preview-js | Extracting previews from a URL or first URL in text | Broader text-input API; less focused on edge-runtime and safe-by-default fetching | | open-graph-scraper | Node Open Graph/Twitter Card scraping with broader options | Node-oriented and larger dependency surface | | metascraper | Rule-based article metadata extraction | More powerful framework; more setup and dependencies | | unfurl.js | Rich nested metadata with fetched oEmbed support | Richer output; not focused on small edge-runtime preview cards |

Measured install footprint

Measured 2026-06-11 via npm install --ignore-scripts of each package's latest version into a clean directory, counting package-lock.json entries and du -sk node_modules:

| Package | Installed packages | node_modules size | | --- | ---: | ---: | | linkpeek | 7 | 1.1 MB | | unfurl.js 6.4.0 | 16 | 3.0 MB | | link-preview-js 4.0.3 | 17 | 5.5 MB | | open-graph-scraper 6.11.0 | 27 | 10.3 MB | | url-metadata 5.4.4 | 30 | 9.7 MB | | metascraper 5.50.6 | 122 | 72.6 MB |

linkpeek's runtime tree contains no HTTP client, no DOM implementation, and no native modules. That is the structural reason it runs on fetch-based edge runtimes. The ESM bundle is ~7 KB gzipped.

Measured speed (same corpus, local server)

From the same-corpus benchmark harness (2026-06-11, Node 24, median ms per end-to-end preview). On small pages linkpeek is tied at the front with unfurl.js; on a realistic 489 kB page the byte cap and head-first parsing are decisive:

| Package | 489 kB page | | --- | ---: | | linkpeek | 0.51 ms | | unfurl.js | 2.38 ms | | link-preview-js (fetch+parse) | 14.70 ms | | url-metadata | 15.41 ms | | metascraper | 18.42 ms | | open-graph-scraper | 208.45 ms |

On real networks the gap widens: linkpeek downloads at most maxBytes (30 KB by default) while the others pull the full page.

See docs/comparison.md for the full speed table, positioning, sourced security/runtime notes, the claim policy, and the commands to reproduce these numbers.

Presets

import { preview, presets } from "linkpeek";

// Default: fast (30 KB limit, head only, no meta-refresh)
const fast = await preview(url);

// Quality: body JSON-LD + image fallback + meta-refresh
const quality = await preview(url, presets.quality);

// Custom: spread a preset and override
const custom = await preview(url, { ...presets.quality, timeout: 3000 });

| Preset | What it enables | | --- | --- | | presets.fast | Default behavior: 30 KB, head-only, no meta-refresh | | presets.quality | 200 KB, body JSON-LD, body image fallback, meta-refresh |

Framework recipes

Full examples are in examples. These are the shortest versions.

Next.js App Router

// app/api/preview/route.ts
import { preview } from "linkpeek";
import { type NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
  const url = req.nextUrl.searchParams.get("url");
  if (!url) return NextResponse.json({ error: "Missing url" }, { status: 400 });

  try {
    return NextResponse.json(await preview(url));
  } catch (err) {
    return NextResponse.json(
      { error: err instanceof Error ? err.message : "Preview failed" },
      { status: 422 },
    );
  }
}

Express

import express from "express";
import { preview } from "linkpeek";

const app = express();

app.get("/api/preview", async (req, res) => {
  const url = typeof req.query.url === "string" ? req.query.url : "";
  if (!url) return res.status(400).json({ error: "Missing url" });

  try {
    res.json(await preview(url));
  } catch (err) {
    res.status(422).json({
      error: err instanceof Error ? err.message : "Preview failed",
    });
  }
});

Cloudflare Workers

import { preview } from "linkpeek";

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url).searchParams.get("url");
    if (!url) return Response.json({ error: "Missing url" }, { status: 400 });

    try {
      const result = await preview(url);
      // Only cache successful previews; 4xx/5xx return a result, not an error
      const cacheControl =
        result.statusCode >= 200 && result.statusCode < 300
          ? "public, max-age=3600"
          : "no-store";
      return Response.json(result, {
        headers: { "Cache-Control": cacheControl },
      });
    } catch (err) {
      return Response.json(
        { error: err instanceof Error ? err.message : "Preview failed" },
        { status: 422 },
      );
    }
  },
};

Use examples/react-preview-card for a browser component that renders the API response into a preview card.

Security Defaults

preview() validates the initial URL and every HTTP redirect before fetching the next target. By default it blocks localhost, private networks, link-local/cloud metadata ranges, multicast/reserved IP ranges, and IPv6 address forms that embed private IPv4 targets.

Production checklist

• Do not forward user cookies, authorization headers, or internal service tokens to arbitrary preview URLs. headers rejects common credential-bearing header names.
• Keep allowPrivateIPs set to false unless the caller is trusted and the network path is intentionally internal.
• Treat returned metadata as untrusted text and URLs. linkpeek filters extracted media/canonical/oEmbed URLs to http: and https:.
• Runtime fetch implementations still own DNS resolution. DNS rebinding protection can vary by platform.
• Cache successful previews by normalized URL so repeated page views do not refetch the same target.
• Tune timeout and maxBytes for your infrastructure. The default preset favors fast preview cards; presets.quality trades more bytes for body fallbacks.
• Handle statusCode and thrown errors with a generic broken-link card instead of blocking the whole page.

Error Handling

HTTP error pages do not throw. A 404 or 500 that returns HTML still resolves with whatever metadata the page has, plus its statusCode. Check it before caching or rendering:

const result = await preview(url);
if (result.statusCode >= 400) {
  // render a broken-link card, skip caching
}

preview() throws a typed LinkpeekError for invalid input, blocked targets, and timeouts. Branch on code instead of matching message strings:

import { LinkpeekError, preview } from "linkpeek";

try {
  const result = await preview(url);
} catch (err) {
  if (err instanceof LinkpeekError) {
    switch (err.code) {
      case "INVALID_URL":              // not a parseable URL
      case "UNSUPPORTED_PROTOCOL":     // not http/https
      case "PRIVATE_NETWORK_BLOCKED":  // SSRF protection triggered
      case "SENSITIVE_HEADER":         // credential-bearing custom header
      case "TOO_MANY_REDIRECTS":
      case "TIMEOUT":
      case "INVALID_OPTIONS":
        break;
    }
  }
  // Aborts via your own `signal` are rethrown as-is (AbortError),
  // and network failures propagate from fetch unchanged.
}

Non-HTML responses

Direct media URLs return a usable result instead of failing: an image URL fills image, a video URL fills video, an audio URL fills audio, and mediaType reflects the content-type group ("image", "video", ...). Other non-HTML content types resolve with null metadata and the response statusCode.

API

preview(url, options?)

Fetches a URL and extracts link preview metadata. Returns Promise<PreviewResult>.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | timeout | number | 8000 | Request timeout in milliseconds. Throws LinkpeekError code TIMEOUT | | maxBytes | number | 30_000 | Maximum bytes to stream | | userAgent | string | "Twitterbot/1.0" | User-Agent sent with requests | | followRedirects | boolean | true | Follow HTTP redirects after validating each target | | maxRedirects | number | 10 | Maximum HTTP redirects to follow | | headers | Record<string, string> | {} | Extra non-sensitive request headers. Common credential-bearing headers are rejected; custom headers are not forwarded on cross-origin redirects | | allowPrivateIPs | boolean | false | Allow private/internal IP targets | | signal | AbortSignal | none | Cancel the request from the caller side | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation (proxies, caching, testing) | | followMetaRefresh | boolean | false | Follow one <meta http-equiv="refresh"> redirect with a delay of 10s or less | | includeBodyContent | boolean | false | Continue scanning <body> for JSON-LD and image fallbacks |

Result Fields

| Field | Type | Description | | --- | --- | --- | | url | string | Final fetched URL | | statusCode | number | HTTP status code. parseHTML() returns 0 | | title | string \| null | og:title -> twitter:title -> JSON-LD -> Dublin Core -> <title> | | description | string \| null | og:description -> twitter:description -> meta[name=description] -> JSON-LD | | image | string \| null | Preview image URL | | imageAlt | string \| null | Image alt text | | imageWidth | number \| null | og:image:width | | imageHeight | number \| null | og:image:height | | siteName | string | og:site_name -> JSON-LD publisher -> hostname | | favicon | string \| null | Favicon URL | | mediaType | string | og:type, defaults to "website" | | canonicalUrl | string | Canonical URL, og:url, or fetched URL | | author | string \| null | JSON-LD author, author meta, or Dublin Core creator | | locale | string \| null | og:locale | | lang | string \| null | HTML language, content-language, or locale prefix | | publishedDate | string \| null | Article, JSON-LD, or Dublin Core date | | keywords | string[] \| null | meta[name=keywords] | | video | string \| null | Safe og:video URL | | audio | string \| null | Safe og:audio URL | | twitterCard | string \| null | Twitter card type | | twitterSite | string \| null | Twitter site handle | | twitterCreator | string \| null | Twitter creator handle | | themeColor | string \| null | Theme color | | oEmbedUrl | string \| null | Discovered oEmbed endpoint URL. Not fetched |

parseHTML(html, baseUrl, options?)

Parses an HTML string directly. Use this when you already have the HTML. Pass { includeBodyContent: true } to continue into <body> for JSON-LD and image fallbacks; by default it keeps the same head-first behavior as preview().

import { parseHTML } from "linkpeek";

const result = parseHTML(
  "<html><head><title>Hello</title></head></html>",
  "https://example.com",
);

console.log(result.title); // "Hello"

validateUrl(url, allowPrivateIPs?) and isPrivateHost(hostname)

The SSRF validation helpers are exported for pre-validating URLs before queueing preview jobs. validateUrl throws a LinkpeekError (INVALID_URL, UNSUPPORTED_PROTOCOL, or PRIVATE_NETWORK_BLOCKED); isPrivateHost returns a boolean.

import { validateUrl } from "linkpeek";

validateUrl("http://169.254.169.254/"); // throws PRIVATE_NETWORK_BLOCKED

FAQ & Troubleshooting

A site returns 403 or empty metadata. Bot protection (Cloudflare challenges, user-agent sniffing) blocks every server-side preview library. This is the most common failure mode in this category and no package solves it. Mitigate: try a different userAgent, cache successful previews aggressively, and render a graceful fallback card from the hostname.

title is null for a single-page app. The page renders its metadata with JavaScript; linkpeek deliberately does not run a browser. presets.quality catches body JSON-LD that many SPAs ship; beyond that you need a headless browser, which is out of scope.

Can I call it from the browser? No, server-side only. Cross-origin pages are unreadable from browsers anyway (CORS), and your preview fetcher should never run on untrusted clients. Put preview() behind an API route (see the recipes above).

I got a preview card for a 404 page. HTTP error pages that return HTML resolve normally with their statusCode set. Check result.statusCode before caching or rendering (see Error Handling).

Development

npm ci
npm run lint
npm run typecheck
npm run test
npm run build
npm audit
npm run package:check
npm run benchmark

Live network tests are opt-in:

LINKPEEK_LIVE_TESTS=1 npm run test

Framework examples are in examples: Next.js, Express, Cloudflare Workers, React, Supabase Edge Functions, and Bun.

License

MIT © Adrian Gruber