Quick start: link previews in TypeScript
Install linkpeek, fetch a URL with preview(), and render Open Graph, Twitter Card, and JSON-LD metadata as a link preview card.
Installation
Install it with any package manager. linkpeek runs on Node.js 22.12+, Bun, Deno and edge runtimes that have fetch, ships ESM and CommonJS with TypeScript declarations, and has one runtime dependency.
npm install linkpeekOn Deno, linkpeek is also on JSR: deno add jsr:@thegruber/linkpeek.
With a coding agent
Paste this task into Claude Code, Cursor, Codex or Copilot. It installs linkpeek, adds a server endpoint and a card component, and follows the safety rules below. Agents can also fetch it from prompt.md.
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/
Usage
import { preview } from "linkpeek";
const result = await preview(
"https://example.com/article"
);
if (result.statusCode < 400) {
console.log(result.title);
console.log(result.description);
console.log(result.image);
}What you get
This is linkpeek parsing this page, live in your browser. preview() returns the same shape for a fetched URL.
{
"title": "TypeScript link preview library · linkpeek",
"description": "Fast, safe link preview library and URL unfurler for TypeScript. Extracts Open Graph, Twitter Card and JSON-LD metadata on Node.js, Bun, Deno and the edge.",
"image": "https://linkpeek.js.org/og/image.png",
"siteName": "linkpeek",
"canonicalUrl": "https://linkpeek.js.org/"
}
A missing field is null. HTTP error pages can still carry metadata, so check statusCode before you cache a result. The API reference lists every option, result field and error code.
Where it runs
| Where | preview(): fetch and parse | parseHTML(): parse only |
|---|---|---|
| Server or API route (Node.js, Bun, Deno) | Yes | Yes |
| Edge (Cloudflare Workers, Vercel) | Yes | Yes |
| Browser | No: browsers may not read other sites' pages | Yes |
Browsers block a page from reading the HTML of another site (CORS). That is why Slack, Discord and X build their previews on a server. Your frontend works the same way: it sends the URL to your own endpoint, which calls preview() and returns the fields as JSON. The homepage demo works exactly like that, and the Next.js guide shows the endpoint.
Parsing existing HTML
Use parseHTML(html, baseUrl) when you already have the HTML. It's synchronous and makes no network requests. The Open Graph parser guide has examples and an interactive parser you can try.
Presets
The default (fast) preset reads the document head and keeps at most 30,000 decoded response-body bytes. The quality preset allows 200,000 bytes, looks in the body for JSON-LD and image fallbacks, and can follow one validated meta refresh.
import { preview, presets } from "linkpeek";
const result = await preview(url, presets.quality);Both limits count the bytes linkpeek keeps, not the total network traffic.
Performance
Most metadata lives in the <head>. The default preset stops reading there and cancels the rest of the response, so most of a large page is never downloaded or parsed. The benchmarks measure this against five other packages.
Integration guides
-
Next.js: App Router endpoint.
-
Cloudflare Workers: extraction and caching.
-
Node.js and Express: a server-side preview API.
-
AI agents: return link metadata from a tool call.
Security and limitations
linkpeek checks every redirect target and blocks private and other non-global IP literals by default. Hostnames are resolved by the runtime's fetch, so on Node.js pass resolveHost to check the DNS answers on every hop, and put outbound network controls in front of a public endpoint. Never forward caller credentials to arbitrary URLs. Read the security model before you expose an endpoint.
linkpeek doesn't run page JavaScript, extract full articles or fetch oEmbed payloads. Troubleshooting covers missing metadata and HTTP errors, and the library comparison points to packages that do those other jobs.