# 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.

```bash
npm install linkpeek
```

On Deno, linkpeek is also on [JSR](https://jsr.io/@thegruber/linkpeek): `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](https://linkpeek.js.org/prompt.md).

<AgentPromptBlock />

## Usage

```ts
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.

A missing field is `null`. HTTP error pages can still carry metadata, so check `statusCode` before you cache a result. The [API reference](https://linkpeek.js.org/api/) 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](https://linkpeek.js.org/integrations/nextjs/) 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](https://linkpeek.js.org/guides/open-graph-parser/) has examples and an [interactive parser](https://linkpeek.js.org/guides/open-graph-parser/#try) 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.

```ts
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](https://linkpeek.js.org/benchmarks/) measure this against five other packages.

## Integration guides

- [Next.js](https://linkpeek.js.org/integrations/nextjs/): App Router endpoint.

- [Cloudflare Workers](https://linkpeek.js.org/integrations/cloudflare-workers/): extraction and caching.

- [Node.js and Express](https://linkpeek.js.org/integrations/node-express/): a server-side preview API.

- [AI agents](https://linkpeek.js.org/integrations/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](https://linkpeek.js.org/security/) before you expose an endpoint.

linkpeek doesn't run page JavaScript, extract full articles or fetch oEmbed payloads. [Troubleshooting](https://linkpeek.js.org/guides/troubleshooting/) covers missing metadata and HTTP errors, and the [library comparison](https://linkpeek.js.org/guides/link-preview-library-comparison/) points to packages that do those other jobs.

Related: [API reference](https://linkpeek.js.org/api/) · [Security model](https://linkpeek.js.org/security/) · [Troubleshooting](https://linkpeek.js.org/guides/troubleshooting/)
