TypeScript link preview library

Turn any URL into a link preview.

Read 26.5 kB of 525 kB, then stopped

server.ts

import { preview } from "linkpeek";const card = await preview("https://github.com/");card.title       // "GitHub · Change is constant. GitHub keeps you ahead. · GitHub"card.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."card.image       // "https://images.ctfassets.net/8aevphvgewt8/76epZKB2wF998m4e4bLLXn/c505f20b00ec70b88b1be5aec42c4be4/OG_image.jpg"

Reads the <head> and drops the rest. Refuses private IPs. One dependency, and it runs on Node.js, Bun, Deno and the edge.

Read the quick start

Install

npm install linkpeek

v3.2.0MITtypes included

Reads the head. Skips the rest.

Most pages keep their preview tags in the <head>. linkpeek parses the response as it streams in and cancels it at </head>, so most of a large page is never downloaded or parsed.

cloudflare.com, fetched when this site was built1335 kB of HTML

<head> 31.6 kB read, then the stream is cancelled

body 1303 kB: never downloaded or parsed

500 kB page with a normal headMedian milliseconds per end-to-end preview. Shorter is faster.
PackageMedian
linkpeek
2.76 ms
unfurl.js
11.0 ms
link-preview-js
48.6 ms
url-metadata
49.5 ms
metascraper
62.6 ms
open-graph-scraper
377 ms
4.0×Faster than unfurl.js on a 500 kB page2.4×Smaller install than unfurl.js1Runtime dependency: htmlparser230 kBThe most it keeps of a response by default

Real previews, captured with linkpeek

Snapshot from Nov 16, 2026. Orange bar: the share of each page linkpeek read.

Let your agent add it.

Paste one task into Claude Code, Cursor, Codex or Copilot and it installs linkpeek, adds a server endpoint and a card component, and sets up caching and the safety rules. Agents can also read prompt.md and llms.txt.

Prompt for your coding agent

Add link previews to this app with linkpeek.

## Context
- linkpeek is a TypeScript library on npm. `preview(url)` fetches a page and returns its Open Graph, Twitter Card and JSON-LD metadata as one flat object; missing fields are `null`.
- It reads only the page's <head>, runs on Node.js 22.12+, Bun, Deno and edge runtimes (Cloudflare Workers, Vercel), and has one dependency.
- Docs written for agents: https://linkpeek.js.org/llms.txt (full text: https://linkpeek.js.org/llms-full.txt).

## Steps
1. Install it with this project's package manager, e.g. `npm install linkpeek`.
2. Add a server endpoint `GET /api/preview?url=…` that calls `preview(url)` and returns `{ title, description, image, siteName, favicon, canonicalUrl, statusCode }` as JSON. Use the framework's server routes (Next.js Route Handler, Express, Hono, a Worker). Browsers may not read other sites (CORS), so fetching stays on the server.
3. Add a link preview card component that calls the endpoint and shows the image, title, description and host, with a loading state and a hostname-only fallback when fields are `null` or the request fails.
4. Cache successful results (`statusCode < 400`) for about a day, keyed by URL. Do not cache errors.

## Rules
- Keep linkpeek's defaults: `allowPrivateIPs` stays off, timeouts and byte limits stay on. On Node.js, pass `resolveHost` (a `node:dns/promises` lookup) so every hop's DNS answers are checked.
- Never forward the user's cookies or authorization headers to the previewed URL.
- Catch `LinkpeekError` and branch on `error.code` (`INVALID_URL`, `UNSUPPORTED_PROTOCOL`, `PRIVATE_NETWORK_BLOCKED`, `TIMEOUT`, `TOO_MANY_REDIRECTS`, `FETCH_FAILED`); return 400 for invalid input and 422 for the rest.
- Rate-limit the endpoint if it is public. Render returned strings as text, never as HTML.

## Done when
- `/api/preview?url=https://github.com` returns a title and an image.
- The card renders for a working URL and falls back cleanly for a broken one.
- Types check and existing tests pass.

Reference: https://linkpeek.js.org/quick-start/ · Next.js: https://linkpeek.js.org/integrations/nextjs/ · Security: https://linkpeek.js.org/security/

Safe by default

  • Every redirect is checked before linkpeek follows it.
  • URLs that point at private, loopback or cloud-metadata IPs, like 169.254.169.254, are refused by default.
  • It keeps at most 30 kB, so a huge response can't exhaust memory.
  • Credential headers are refused, and custom headers are dropped on cross-origin redirects.
Security model and limits

Add link previews to your app.

npm install linkpeek
Read the quick start