TypeScript link preview library
Turn any URL into a link preview.
github.comGitHub · Change is constant. GitHub keeps you ahead. · GitHubJoin 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.Preview tags6/6 found
- titlefound
- descriptionfound
- imagefound
- image altfound
- twitter:cardfound
- faviconfound
Read 26.5 kB of 525 kB, then stoppedsnapshot 1/10 · Nov 16, 2026
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.
Install
npm install linkpeekv3.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.
<head> 31.6 kB read, then the stream is cancelled
body 1303 kB: never downloaded or parsed
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.
Runs where fetch runs
Add link previews to your app.
npm install linkpeek






