link-preview-kit

High-performance, extensible TypeScript Link Preview & Metadata Extraction Engine. Built for production services with TLS fingerprinting, zero-download HTTP Range media probing, Data-URI parsing, and a modular provider architecture.

Features

• Zero-Download HTTP Range Probing: Measures video/audio duration, dimensions (width/height), file size, and MIME types of non-faststart MP4, WebM, MOV, MKV, and audio files by downloading only 64KB-256KB headers.
• Inline Data-URI Support: Instantly parses data:image/svg+xml;base64,... and PNG/JPEG data URIs with zero network requests.
• Modular Provider Architecture: Built-in specialized extractors for Telegram, Twitter / X, YouTube, Instagram, TikTok, Spotify, and SoundCloud.
• Configurable Sanitization: Easily toggle HTTPS URL upgrading, HTML tag stripping, and description text truncation.
• Dual ESM & CommonJS: Supports both import and require() natively with auto-generated TypeScript .d.ts type declarations.
• TLS Scraper: Bypasses basic bot checks using got-scraping Chrome TLS fingerprinting with optional Puppeteer Stealth fallback.

Installation

npm install link-preview-kit
# or
yarn add link-preview-kit
# or
pnpm add link-preview-kit

Quick Start

ESM (import)

import { extractLinkPreview } from "link-preview-kit";

const result = await extractLinkPreview("https://t.me/FarsBots/248");

console.log(result);
/*
{
  success: true,
  data: {
    url: 'https://t.me/FarsBots/248',
    site_name: 'Telegram',
    title: 'Telegram Channel',
    description: 'Channel description...',
    media_url: null,
    media_type: null,
    media_width: null,
    media_height: null,
    media_duration: null,
    file_size: null,
    mime_type: null
  },
  meta: {
    strategy_used: 'provider:telegram',
    execution_time_ms: 1240
  }
}
*/

CommonJS (require)

const { extractLinkPreview } = require("link-preview-kit");

extractLinkPreview("https://www.youtube.com/watch?v=dQw4w9WgXcQ").then(
  (result) => console.log(result.data),
);

Options & Sanitization

All text and URL sanitization options are fully configurable:

const result = await extractLinkPreview("http://example.com/article", {
  // Timeout in milliseconds (default: 4000)
  timeout: 5000,

  // Upgrade insecure http:// URLs to https:// (default: true)
  sanitizeUrl: true,

  // Automatically strip HTML tags from extracted text (default: true)
  stripHtml: true,

  // Truncate description length. Set to a number or null to disable (default: 160)
  maxDescriptionLength: 200, // or null to disable truncation

  // Custom User-Agent string
  userAgent: "MyCustomBot/1.0",

  // Bypass SSL certificate validation for internal/dev servers (default: true)
  allowInsecureTls: true,

  // Validate accessibility and MIME type of extracted media URLs (default: true)
  validateMediaUrl: true,

  // Filter allowed media types ("photo" | "video" | "audio") (default: ["photo", "video"])
  allowedMediaTypes: ["photo", "video"],

  // Enable optional Puppeteer Stealth fallback for JS-heavy sites (default: false)
  enablePuppeteerFallback: false,
});

Custom Providers

You can extend link-preview-kit by creating and registering custom providers:

import { Provider, createLinkPreviewEngine } from "link-preview-kit";

const customGithubProvider: Provider = {
  name: "github-repo",
  match(url: string) {
    return url.includes("github.com");
  },
  async extract(url: string) {
    return {
      url,
      site_name: "GitHub",
      title: "Custom GitHub Extractor",
      description: "Extracted repository preview",
      media_url: null,
      media_type: null,
      media_width: null,
      media_height: null,
      media_duration: null,
      file_size: null,
      mime_type: null,
    };
  },
};

const engine = createLinkPreviewEngine();
engine.registerProvider(customGithubProvider);

const result = await engine.extract(
  "https://github.com/alikm6/link-preview-kit",
);

License

MIT License © 2026 Ali Karimi (https://github.com/alikm6)