# How to Build Slack-Style Link Previews with Next.js Every chat app does it. You paste a link and a rich card appears with a title, description, and image. Slack does it. Discord does it. Teams, iMessage, and basically every messaging tool built in the last five years does it too. That card is called a link preview, and the process of generating it is often called URL unfurling. At its core, it works by fetching the page's metadata and rendering it in a structured card. This tutorial walks through building a basic Slack-style link preview system for your own app using the Next.js App Router. You'll set up a Route Handler that fetches metadata for a URL, normalizes it into a clean object, and renders it as a polished preview card in a Next.js frontend. We'll handle one URL at a time. This isn't a full chat platform. It's the smallest useful version of the problem, which makes it a great starting point. By the end, you'll also see where this approach breaks down in production and when a dedicated [Link Preview API](/products/link-preview-api) makes more sense. ![Link preview pipeline: URL goes to server, metadata is extracted, preview card renders](/images/blogs/images/build-link-preview-architecture.webp) ## What a Link Preview Actually Needs A link preview is just structured metadata displayed as a card. Most websites expose this data through [Open Graph tags](/what-is-open-graph), standard HTML meta tags, or sometimes Twitter/X card tags. The fields that matter for a typical preview card are: - **Title**: the page headline - **Description**: a short summary of the page - **Image**: the thumbnail or featured image - **Site name**: where the link is from (e.g. "GitHub" or "Stripe") - **URL**: the full page address - **Domain**: the hostname, useful as a fallback label Not every page exposes all of these. Some sites have well-maintained OG tags. Others have almost nothing. Your preview system needs to handle both gracefully. If you want a deeper look at how these previews work across different platforms, check out our guide on [what is a link preview](/what-is-a-link-preview). ## What You'll Build Here's the flow: 1. A user submits a URL 2. Your server receives that URL — and has to treat it as untrusted input 3. The server fetches the page and reads its metadata (Open Graph, Twitter Card, and standard HTML tags) 4. The app normalizes that metadata into a consistent object 5. The frontend renders a Slack-style preview card The implementation splits into two layers: a Next.js Route Handler does the server-side metadata fetch, and a lightweight client component handles the rendering. Fetching happens server-side mainly because browsers block arbitrary cross-origin page fetches — client-side JavaScript can't just request `https://stripe.com` and read back its HTML. Running the fetch on the server sidesteps that restriction. It also means your server is now responsible for whatever URL a caller hands it, which is exactly the tradeoff we'll cover in the next section. This is intentionally a one-URL-at-a-time system. No WebSocket unfurling, no job queues, no caching layer. Just the core preview pipeline that every real implementation is built on top of. Once you understand how this works, extending it becomes a lot more approachable. ## Step 1: Define the Preview Data Shape Before writing any fetch logic, define the shape of the data your card needs. Thinking from the output backward keeps your implementation focused. ```typescript // lib/types.ts export interface LinkPreview { title: string; description: string; image: string; siteName: string; url: string; domain: string; } ``` Exporting it means the backend and frontend share one definition instead of each keeping their own copy in sync by hand. These six fields cover what most Slack and Discord-style preview cards display. You could add a favicon or canonical URL later, but those are secondary. Start with the basics and expand only when your UI needs more. One thing worth noting early: not every website fills in all of these fields, and the raw values can be messy — untrimmed, empty, or pointing at a relative image path. Your card should still look good when that happens. We'll clean that up over the next couple of steps. ## Step 2: Fetch Metadata for a URL This is where the implementation starts. The Route Handler needs to accept a URL, fetch the page, and pull out the metadata that matters. You'll need one package: ```bash npm install cheerio ``` Cheerio loads the returned HTML and lets you query it with CSS selectors, similar to how jQuery works but running on the server. We'll use the native `fetch` API for the HTTP request, so there's no separate HTTP client to install. **A security note before you go further.** This example accepts an arbitrary URL from the caller and fetches it directly. That's fine for learning or a local prototype, but a publicly reachable endpoint that fetches whatever URL a user submits is a textbook SSRF (server-side request forgery) target — a malicious caller could point it at your internal network, cloud metadata endpoints, or other services you don't intend to expose. Moving the fetch server-side solves the browser's CORS restriction, but it also makes your server responsible for safely handling arbitrary, untrusted URLs. A production version needs to validate the URL scheme, block requests to private/internal IP ranges, handle redirects carefully (a redirect can point somewhere the original URL didn't), and enforce timeouts and response size limits. We're intentionally not building that hardening into this tutorial — it's one of the production challenges covered later on. Here's the core fetch function: ```typescript // lib/fetchPreview.ts import * as cheerio from 'cheerio'; import type { LinkPreview } from './types'; const getMeta = ($: cheerio.CheerioAPI, selectors: string[]): string => { for (const sel of selectors) { const val = $(sel).attr('content'); if (val) return val; } return ''; }; const resolveUrl = (maybeUrl: string, base: string): string => { if (!maybeUrl) return ''; try { return new URL(maybeUrl, base).toString(); } catch { return ''; } }; export async function fetchLinkPreview(targetUrl: string): Promise { const response = await fetch(targetUrl, { headers: { 'User-Agent': 'Mozilla/5.0 (compatible; LinkPreviewBot/1.0)', }, signal: AbortSignal.timeout(5000), }); if (!response.ok) { throw new Error(`Failed to fetch URL: ${response.status}`); } const html = await response.text(); const $ = cheerio.load(html); const title = getMeta($, [ 'meta[property="og:title"]', 'meta[name="twitter:title"]', ]) || $('title').text() || ''; const description = getMeta($, [ 'meta[property="og:description"]', 'meta[name="twitter:description"]', 'meta[name="description"]', ]); const rawImage = getMeta($, [ 'meta[property="og:image"]', 'meta[name="twitter:image"]', ]); const siteName = getMeta($, [ 'meta[property="og:site_name"]', ]); // normalization happens in the next step } ``` The `getMeta` helper tries multiple selectors in priority order and returns the first match. That gives us a sensible fallback order: prefer Open Graph metadata, then Twitter Card metadata, then standard HTML metadata. ## Step 3: Normalize the Response Raw metadata from a page is rarely in the exact shape your UI wants. Field names vary, some values are missing, image URLs are sometimes relative, and different sources sometimes disagree. Before passing anything to the frontend, normalize it into a predictable object — without inventing data that isn't actually there. Here's how we complete the `fetchLinkPreview` function: ```typescript // continuing fetchLinkPreview... const domain = new URL(targetUrl).hostname; const image = resolveUrl(rawImage, targetUrl); return { title: title.trim(), description: description.trim(), image, siteName: siteName || domain, url: targetUrl, domain, }; } ``` Two decisions worth calling out. First, `resolveUrl` turns a relative image path like `/images/social-card.jpg` into a full URL by resolving it against the page's own address — without that step, an `` tag on your frontend would try (and fail) to load it relative to your own domain instead of the target site. Second, if `siteName` is empty we fall back to the domain, since a raw hostname is still a usable label. Notice that `title` and `description` stay as whatever the page actually provided, even if that's an empty string. We're intentionally not swapping in a placeholder like `"Untitled"` here — that kind of display fallback belongs in the UI, not in the normalized data. Baking `"Untitled"` into this object would make it impossible for the frontend to tell "this page has no title" from "this page's title is literally the word Untitled," which is a subtle bug worth avoiding. We'll add display-level fallbacks in Step 5. Now expose the function as a Route Handler: ```typescript // app/api/preview/route.ts import { NextRequest, NextResponse } from 'next/server'; import { fetchLinkPreview } from '@/lib/fetchPreview'; export async function GET(request: NextRequest) { const url = request.nextUrl.searchParams.get('url'); if (!url) { return NextResponse.json({ error: 'URL is required' }, { status: 400 }); } try { const preview = await fetchLinkPreview(url); return NextResponse.json(preview); } catch { return NextResponse.json({ error: 'Could not generate preview' }, { status: 500 }); } } ``` That's the entire backend. A URL goes in, a clean preview object comes out. The frontend never needs to think about meta tag selectors or HTML parsing. ## Step 4: Render a Slack-Style Preview Card Now for the visual side. If you've seen a link unfurl in Slack, you'll recognize the pattern: a colored accent bar on the left side, the site name in small text, a bold title, a short description underneath, and an image. Here's a component that captures that look: ```tsx // components/LinkPreviewCard.tsx import type { LinkPreview } from '@/lib/types'; type LinkPreviewCardProps = LinkPreview; const LinkPreviewCard = ({ title, description, image, siteName, url, domain, }: LinkPreviewCardProps) => { return ( {image && ( {title}

{title}

{description && (

{description}

)}

); }; export default LinkPreviewCard; ``` The colored left border is the signature Slack touch. The rest is clean typography and intentional spacing. The entire card links to the original URL so clicking it opens the page in a new tab. ![Rendered Slack-style preview card showing Stripe metadata with accent border, title, and description](/images/blogs/images/build-link-preview-card-example.webp) To wire everything together, create a simple test page: ```tsx // app/preview/page.tsx 'use client'; import { useState } from 'react'; import LinkPreviewCard from '@/components/LinkPreviewCard'; import type { LinkPreview } from '@/lib/types'; export default function PreviewPage() { const [url, setUrl] = useState(''); const [preview, setPreview] = useState(null); const [loading, setLoading] = useState(false); const handleFetchPreview = async () => { if (!url) return; setLoading(true); try { const res = await fetch(`/api/preview?url=${encodeURIComponent(url)}`); if (!res.ok) { throw new Error('Could not generate preview'); } const data: LinkPreview = await res.json(); setPreview(data); } catch { setPreview(null); } setLoading(false); }; return (

Link Preview Generator

setUrl(e.target.value)} placeholder="Paste a URL..." style={{ flex: 1, padding: '10px 12px', fontSize: '14px', borderRadius: '6px', border: '1px solid #d1d5db', }} />

{preview && }

); } ``` Paste a URL, click Preview, and the card appears. ## Step 5: Handle Missing or Weak Metadata The preview looks great with well-tagged pages. But real websites are messy. Some pages have no image at all. Some return descriptions that run on for hundreds of characters. Others don't even have a usable title. Your card needs to handle all of this without breaking. Here's the component with simple fallback logic added: ```tsx const LinkPreviewCard = ({ title, description, image, siteName, url, domain, }: LinkPreviewCardProps) => { if (!title && !description) return null; const displayTitle = title.length > 120 ? title.slice(0, 117) + '...' : title; const displayDescription = description.length > 200 ? description.slice(0, 197) + '...' : description; return ( {image && ( {displayTitle}

{ (e.target as HTMLImageElement).style.display = 'none'; }} /> )}

{siteName || domain}

{displayTitle || 'Untitled page'}

{displayDescription && (

{displayDescription}

)}

); }; ``` Here's what this handles: - **No image**: the image section simply doesn't render - **Broken image**: the `onError` handler hides it so the card doesn't show a broken icon - **Long title or description**: truncated with an ellipsis to keep the card compact - **No title AND no description**: returns null so you don't get an empty card - **Missing site name**: falls back to the raw domain This is also why keeping `title` and `description` unmodified in Step 3 mattered: the `if (!title && !description) return null` check only works correctly if an empty title is actually an empty string, not a string that already says "Untitled." The display fallback (`displayTitle || 'Untitled page'`) belongs here, in the component, not upstream in the fetch logic. These are small things, but they make the difference between a preview that feels polished and one that breaks on half the URLs your users paste. ## Step 6: Test With a Real URL Time to see it working. Paste `https://stripe.com` into the input and hit Preview. Here's the JSON your Route Handler returns: ```json { "title": "Stripe | Financial Infrastructure to Grow Your Revenue", "description": "Stripe is a financial services platform that helps all types of businesses accept payments, build flexible billing models, and manage money movement.", "image": "https://images.stripeassets.com/fzn2n1nzq965/XtX984S1GJVsVOXFC7kMu/01988281e867728dfb09aa7793a6e3b9/Stripe.jpg?q=80", "siteName": "Stripe", "url": "https://stripe.com", "domain": "stripe.com" } ``` That maps directly into the card: the Stripe OG image across the top, the site name and title below it, and the description underneath. Clean and readable. Try a few different URLs. You'll notice that pages with strong OG tags produce great previews. Pages without them produce weaker results, sometimes with missing images or generic titles pulled from the `` tag. That inconsistency is exactly why production-grade unfurling is harder than it looks. ![HTML meta tags parsed and normalized into structured preview card fields](/images/blogs/images/build-link-preview-html-to-card.webp) ## Quick Recap Here's what the basic link preview pipeline looks like: 1. Take a URL 2. Fetch the page and read its meta tags 3. Normalize the data into a clean object 4. Render a preview card 5. Add fallbacks for missing or weak fields For a single URL at a time, this is often enough to get started. The approach is straightforward, the code is small, and the result is immediately useful. {{ARTICLE_PRODUCT_CTA}} But the moment you start unfurling links at any real scale, things get more complicated. ## Why Link Previews Get Harder in Production Building a preview for one URL is easy. Making it reliable and safe across thousands of different websites is a very different problem. Here's what you'll run into. **Untrusted URLs and SSRF.** The moment this endpoint is publicly reachable, every URL it receives is attacker-controlled input. Without scheme validation, private-network blocking, and redirect checks, a fetch-any-URL endpoint can be turned into a way to probe your internal infrastructure. **Inconsistent metadata.** Some sites have perfect Open Graph tags with high-quality images, clear titles, and concise descriptions. Others have almost nothing. Some technically have meta tags but they contain unhelpful content, like the site name repeated as the description or a generic placeholder image. **Conflicting sources.** A page's OG title, Twitter card title, and HTML `<title>` tag don't always agree. The same goes for images and descriptions from different tag types. Your unfurler needs a priority system to decide which source to trust, and even then you'll hit edge cases regularly. **JavaScript-rendered pages.** Single-page apps and heavily dynamic sites often don't include meta tags in their initial HTML response. A basic HTTP request returns an empty shell. Getting the actual metadata requires a headless browser, which adds latency, complexity, and infrastructure cost. **Bot protection, blocking, and rate limits.** Some domains detect automated requests and reject them outright. Others serve CAPTCHAs or redirect to login pages. If your users are pasting links from all over the web, you'll hit these walls often. **Redirects and URL edge cases.** The URL a user pastes isn't always the URL that ends up serving content — shorteners, tracking redirects, and canonical-URL differences all mean the page you fetch may not be the page you think you're fetching. Each hop through a redirect also needs the same safety checks as the original URL. **Broken or low-quality images.** The URL in an OG image tag isn't always valid. Sometimes it's a relative path that doesn't resolve. Sometimes the image is tiny, corrupted, or sits behind authentication. Validating image quality adds another layer of logic to maintain. **Timeouts and oversized responses.** Some pages take a long time to respond, and some return megabytes of HTML for a request that only needs a few meta tags. Without limits on both, a handful of slow or bloated targets can tie up server resources. **Caching and freshness.** Fetching and parsing a page every time someone requests a preview is slow and wasteful. You need a caching layer. But caches introduce staleness, and some pages update their metadata frequently. Getting cache invalidation right is a project in itself. **Ongoing monitoring and maintenance.** Websites change their markup, update their CMS configurations, and restructure their pages constantly. A preview system that works today can silently break next month when a popular site updates their template. Keeping it working means monitoring, updating selectors, and handling new edge cases as they surface. ![Common link preview challenges: SSRF and untrusted URLs, missing tags, JS rendering, rate limits, broken images](/images/blogs/images/build-link-preview-challenges.webp) None of these are unsolvable. But solving them all well, and keeping them solved over time, takes significantly more effort than the basic version we built above. ## When DIY Still Makes Sense None of this means you should always reach for an API. The tutorial above is a perfectly reasonable production choice when: - You're learning how unfurling works, not shipping it to end users yet - You're prototyping a feature and validating the idea before investing further - You're only ever previewing a small, known set of domains you control or trust - Your scale and reliability requirements are genuinely low, and an occasional broken preview isn't costly If you're learning or prototyping, the code above is a good starting point. For a production system limited to known domains, you'll still want to restrict which URLs can be fetched and add the basic security and resource limits appropriate for your environment — the endpoint as written accepts any URL, and that doesn't change just because you only intend to use it with a handful of trusted domains. The calculus changes further once your endpoint is public, your traffic grows, or the set of URLs you need to support becomes unpredictable. ## DIY vs Link Preview API | | DIY (this tutorial) | Link Preview API | |---|---|---| | Basic metadata extraction | Works for well-tagged pages | Works across a wide range of sites | | Fallback metadata | Manual, selector-based | Built in, tuned across many domains | | JavaScript-rendered pages | Not handled — needs a headless browser you'd add yourself | Handled automatically | | Blocking/proxy handling | Not handled | Proxy tiers and retry built in | | Caching | Not included | Built in | | Target URL fetching / SSRF exposure | Your infrastructure makes the request and must secure it | OpenGraph.io fetches the target URL | | Maintenance | Ongoing, as target sites change | Handled by the provider | This isn't about whether you can build the DIY version — you clearly can, you just did. It's about which side of this table you want your team spending time on. ## Use OpenGraph.io for Production Link Previews The [Link Preview API](/products/link-preview-api) handles the hard parts of metadata extraction so you don't have to. Send a URL, get back a structured response with the exact fields your preview card needs — plus proxy handling, JS rendering, and retry logic already built in. Here's what a request to the current v3 Site API looks like: ```javascript const appId = 'YOUR_APP_ID'; const targetUrl = encodeURIComponent('https://stripe.com'); const response = await fetch( `https://opengraph.io/api/3.0/site/${targetUrl}?app_id=${appId}` ); const data = await response.json(); ``` And here's what comes back: ```json { "hybridGraph": { "title": "Stripe | Financial Infrastructure to Grow Your Revenue", "description": "Stripe is a financial services platform that helps all types of businesses accept payments, build flexible billing models, and manage money movement.", "type": "website", "image": "https://images.stripeassets.com/fzn2n1nzq965/XtX984S1GJVsVOXFC7kMu/01988281e867728dfb09aa7793a6e3b9/Stripe.jpg?q=80", "url": "https://stripe.com/", "site_name": "Stripe" }, "openGraph": { "title": "Stripe | Financial Infrastructure to Grow Your Revenue", "description": "Stripe is a financial services platform that helps all types of businesses accept payments, build flexible billing models, and manage money movement.", "type": "website", "image": { "url": "https://images.stripeassets.com/fzn2n1nzq965/XtX984S1GJVsVOXFC7kMu/01988281e867728dfb09aa7793a6e3b9/Stripe.jpg?q=80" }, "url": "https://stripe.com/" } } ``` `hybridGraph` gives you the best available data by merging OG tags, Twitter Card data, and HTML-inferred values into a single reliable object — that's the one your `LinkPreviewCard` component should read from. `openGraph` shows the raw OG tags exactly as found on the page, which is useful if you need to know what a site actually published versus what OpenGraph.io inferred. Check the [Site API docs](/docs/api/site) for the full parameter list and response format, including retry and proxy options. Compare this to the DIY approach we built. No cheerio. No meta tag selectors. No SSRF hardening to build and maintain yourself. Just a URL in, structured data out — plugging straight into the same `LinkPreviewCard` component with zero normalization needed on your end. Three places to go from here: - Evaluate the product: [Link Preview API](/products/link-preview-api) - Implement it: [Site API docs](/docs/api/site) - Test a URL right now, no code required: [Link Preview Tool](/link-preview) ## Final Thoughts A basic Slack-style link preview is genuinely achievable in an afternoon: fetch the page, read the meta tags, normalize the response, render a card. If you're learning or prototyping, build it — understanding how unfurling works from the ground up is valuable on its own. What's harder to build in an afternoon is the version that's safe to expose publicly and reliable across every URL your users throw at it. That's the point where most teams reach for the [Link Preview API](/products/link-preview-api) instead of continuing to maintain the infrastructure themselves. </article></body></html>