Building a Link Preview Service in 30 Minutes

Link previews transform bare URLs into rich cards with images, titles, and descriptions. You've seen them everywhere: Slack, Twitter, Discord, iMessage. They make links more engaging and give users context before clicking.

In this guide, we'll build a complete link preview service that generates thumbnail screenshots, extracts metadata, and caches results for performance.

What We're Building

Our service will:

Accept a URL as input
Fetch the page's Open Graph metadata (title, description, image)
Capture a screenshot as a fallback thumbnail
Cache results to avoid repeated processing
Return a structured preview object

The final API will look like this:

curl 'https://your-api.com/preview?url=https://example.com'

Response:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "description": "This domain is for use in illustrative examples.",
  "image": "https://your-cdn.com/previews/abc123.png",
  "favicon": "https://example.com/favicon.ico"
}

Architecture Overview

We'll use a simple Node.js server with three main components:

Metadata extractor: Fetches and parses Open Graph tags
Screenshot service: Captures page thumbnails via API
Cache layer: Stores results in Redis

Request → Check Cache → [Cache Hit] → Return cached preview
                     ↓
              [Cache Miss]
                     ↓
         Fetch metadata + Screenshot
                     ↓
              Store in cache
                     ↓
              Return preview

Step 1: Project Setup

Create a new Node.js project:

mkdir link-preview-service
cd link-preview-service
npm init -y
npm install express node-fetch cheerio redis

Basic server structure:

import express from 'express';
import { createClient } from 'redis';

const app = express();
const redis = createClient();

await redis.connect();

app.get('/preview', async (req, res) => {
  const { url } = req.query;

  if (!url) {
    return res.status(400).json({ error: 'URL is required' });
  }

  try {
    const preview = await getPreview(url);
    res.json(preview);
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate preview' });
  }
});

app.listen(3000, () => {
  console.log('Preview service running on port 3000');
});

Step 2: Extracting Metadata

Open Graph tags live in the <head> of HTML documents. We'll fetch the page and parse them with Cheerio:

import fetch from 'node-fetch';
import * as cheerio from 'cheerio';

async function extractMetadata(url) {
  const response = await fetch(url, {
    headers: {
      'User-Agent': 'LinkPreviewBot/1.0'
    },
    timeout: 5000
  });

  const html = await response.text();
  const $ = cheerio.load(html);

  // Extract Open Graph tags
  const getMetaContent = (property) => {
    return $(`meta[property="${property}"]`).attr('content') ||
           $(`meta[name="${property}"]`).attr('content');
  };

  return {
    title: getMetaContent('og:title') || $('title').text() || '',
    description: getMetaContent('og:description') ||
                 getMetaContent('description') || '',
    image: getMetaContent('og:image') || '',
    siteName: getMetaContent('og:site_name') || '',
    favicon: $('link[rel="icon"]').attr('href') ||
             $('link[rel="shortcut icon"]').attr('href') ||
             new URL('/favicon.ico', url).href
  };
}

Always set a descriptive User-Agent header. Some sites block requests without one, and it helps site owners understand their traffic.

Step 3: Capturing Screenshots

When a page lacks an Open Graph image, we'll capture a screenshot. This is where the Allscreenshots API shines: there is no browser management needed:

async function captureScreenshot(url) {
  const response = await fetch('https://api.allscreenshots.com/v1/screenshots', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.SCREENSHOT_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: url,
      width: 1200,
      height: 630,  // Standard OG image ratio
      format: 'png',
      delay: 1000,  // Wait for content to load
      blockAds: true
    })
  });

  if (!response.ok) {
    throw new Error('Screenshot capture failed');
  }

  const imageBuffer = await response.arrayBuffer();

  // Upload to your CDN/storage
  const imageUrl = await uploadToStorage(imageBuffer);

  return imageUrl;
}

The 1200x630 dimensions match the standard Open Graph image ratio, so previews will look correct when shared on social platforms.

Step 4: Caching Results

Link previews rarely change, so aggressive caching makes sense. We'll cache for 24 hours:

const CACHE_TTL = 60 * 60 * 24; // 24 hours in seconds

async function getPreview(url) {
  // Normalize URL for consistent cache keys
  const cacheKey = `preview:${normalizeUrl(url)}`;

  // Check cache first
  const cached = await redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // Generate fresh preview
  const metadata = await extractMetadata(url);

  // Capture screenshot if no OG image
  let image = metadata.image;
  if (!image) {
    image = await captureScreenshot(url);
  }

  const preview = {
    url,
    title: metadata.title,
    description: metadata.description,
    image,
    favicon: metadata.favicon,
    siteName: metadata.siteName,
    generatedAt: new Date().toISOString()
  };

  // Store in cache
  await redis.setEx(cacheKey, CACHE_TTL, JSON.stringify(preview));

  return preview;
}

function normalizeUrl(url) {
  const parsed = new URL(url);
  // Remove trailing slashes, lowercase hostname
  return `${parsed.protocol}//${parsed.hostname.toLowerCase()}${parsed.pathname.replace(/\/$/, '')}`;
}

Consider adding a cache-busting mechanism for site owners who update their pages. A simple ?refresh=true parameter works well.

Step 5: Error Handling

Real-world URLs fail in many ways. Handle them gracefully:

async function getPreview(url) {
  try {
    // Validate URL
    new URL(url);
  } catch {
    throw new Error('Invalid URL');
  }

  // Check for blocked domains
  const blocked = ['localhost', '127.0.0.1', '0.0.0.0'];
  const hostname = new URL(url).hostname;
  if (blocked.some(b => hostname.includes(b))) {
    throw new Error('URL not allowed');
  }

  try {
    const metadata = await extractMetadata(url);
    // ... rest of logic
  } catch (error) {
    if (error.code === 'ETIMEDOUT') {
      throw new Error('Request timed out');
    }
    if (error.code === 'ENOTFOUND') {
      throw new Error('Domain not found');
    }
    throw error;
  }
}

Always validate and sanitize URLs before processing. Server-side request forgery (SSRF) attacks can use your preview service to probe internal networks.

Step 6: Rate Limiting

Protect your service from abuse with rate limiting:

import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // 100 requests per minute
  message: { error: 'Too many requests' }
});

app.use('/preview', limiter);

Performance Optimizations

A few tweaks to make the service faster:

Parallel Requests

Fetch metadata and screenshots concurrently when possible:

async function getPreview(url) {
  const metadata = await extractMetadata(url);

  if (metadata.image) {
    return buildPreview(url, metadata);
  }

  // Only capture screenshot if needed
  const screenshot = await captureScreenshot(url);
  return buildPreview(url, { ...metadata, image: screenshot });
}

Preemptive Caching

For frequently requested URLs, refresh the cache before it expires:

async function getPreview(url) {
  const cacheKey = `preview:${normalizeUrl(url)}`;
  const cached = await redis.get(cacheKey);

  if (cached) {
    const preview = JSON.parse(cached);
    const age = Date.now() - new Date(preview.generatedAt).getTime();

    // Refresh in background if cache is getting stale
    if (age > CACHE_TTL * 0.8 * 1000) {
      refreshPreview(url).catch(() => {}); // Fire and forget
    }

    return preview;
  }

  // Generate fresh preview
  // ...
}

Putting It All Together

Here's the complete service:

import express from 'express';
import fetch from 'node-fetch';
import * as cheerio from 'cheerio';
import { createClient } from 'redis';
import rateLimit from 'express-rate-limit';

const app = express();
const redis = createClient();

await redis.connect();

const limiter = rateLimit({
  windowMs: 60 * 1000,
  max: 100
});

app.use('/preview', limiter);

app.get('/preview', async (req, res) => {
  const { url } = req.query;

  if (!url) {
    return res.status(400).json({ error: 'URL required' });
  }

  try {
    const preview = await getPreview(url);
    res.json(preview);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Conclusion

You now have a production-ready link preview service. The key ingredients:

Metadata extraction for titles and descriptions
Screenshot fallbacks for pages without OG images
Aggressive caching to minimize API calls
Error handling for the messy real world

From here, you could add support for Twitter Cards, oEmbed providers like YouTube, or image resizing for different use cases. The foundation is solid, so build on it.

Building a Link Preview Service in 30 Minutes

What We're Building

Architecture Overview

Step 1: Project Setup

Step 2: Extracting Metadata

Step 3: Capturing Screenshots

Step 4: Caching Results

Step 5: Error Handling

Step 6: Rate Limiting

Performance Optimizations

Parallel Requests

Preemptive Caching

Putting It All Together

Conclusion

Related Posts

How to capture full-page screenshots in Figma (without browser extensions)

How to take full page screenshots in Chrome (2026)

How to take website screenshots from the command line

Start capturing screenshots in minutes

What We're Building

Architecture Overview

Step 1: Project Setup

Step 2: Extracting Metadata

Step 3: Capturing Screenshots

Step 4: Caching Results

Step 5: Error Handling

Step 6: Rate Limiting

Performance Optimizations

Parallel Requests

Preemptive Caching

Putting It All Together

Conclusion