or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdlink-preview.mdpre-fetched-content.mdsecurity-configuration.md
tile.json

tessl/npm-link-preview-js

JavaScript module to extract and fetch HTTP link information from blocks of text via OpenGraph and meta tag parsing.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/link-preview-js@3.0.x

To install, run

npx @tessl/cli install tessl/npm-link-preview-js@3.0.0

index.mddocs/

Link Preview JS

Link Preview JS is a robust TypeScript library that extracts comprehensive metadata from HTTP URLs and HTML content. It parses OpenGraph tags, Twitter Card metadata, and standard HTML elements to generate rich link previews including titles, descriptions, images, videos, and favicons. The library includes built-in security features to prevent SSRF attacks and provides flexible configuration options for headers, timeouts, and redirect handling.

Package Information

  • Package Name: link-preview-js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install link-preview-js

Core Imports

import { getLinkPreview, getPreviewFromContent } from "link-preview-js";

For CommonJS:

const { getLinkPreview, getPreviewFromContent } = require("link-preview-js");

Basic Usage

import { getLinkPreview } from "link-preview-js";

// Extract preview from URL
const preview = await getLinkPreview("https://www.youtube.com/watch?v=dQw4w9WgXcQ");

console.log(preview.title);        // "Rick Astley - Never Gonna Give You Up"
console.log(preview.description);  // Video description
console.log(preview.images[0]);    // Thumbnail URL
console.log(preview.siteName);     // "YouTube"

// Extract from text containing URL
const textPreview = await getLinkPreview(
  "Check out this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
);

// With custom options
const customPreview = await getLinkPreview("https://example.com", {
  headers: { "User-Agent": "MyBot/1.0" },
  timeout: 5000,
  followRedirects: "follow"
});

Architecture

Link Preview JS is built around several key components:

  • URL Detection: Automatic URL extraction from text using regex patterns with security validations
  • HTTP Client: Built-in fetch with configurable timeouts, headers, and redirect handling
  • HTML Parser: Cheerio-based DOM parsing for extracting metadata from various tag types
  • Content Type Handler: Specialized parsers for different media types (HTML, images, audio, video, applications)
  • Security Layer: SSRF protection through DNS resolution validation and private IP blocking
  • Metadata Extraction: Multi-source extraction from OpenGraph, Twitter Cards, and standard HTML meta tags

Capabilities

Link Preview Extraction

Comprehensive link preview generation from URLs or text containing URLs. Automatically detects the first valid HTTP/HTTPS URL and extracts rich metadata including titles, descriptions, images, videos, and favicons.

function getLinkPreview(
  text: string,
  options?: ILinkPreviewOptions
): Promise<ILinkPreviewResponse>;

Link Preview Extraction

Pre-fetched Content Processing

Parse pre-fetched HTML content to extract link preview metadata without making additional HTTP requests. Useful for scenarios where content is already available from other sources or when implementing custom fetching logic.

function getPreviewFromContent(
  response: IPreFetchedResource,
  options?: ILinkPreviewOptions
): Promise<ILinkPreviewResponse>;

Pre-fetched Content Processing

Security and Configuration

Advanced security features and configuration options for customizing request behavior, handling redirects, and preventing SSRF attacks through DNS resolution validation.

interface ILinkPreviewOptions {
  headers?: Record<string, string>;
  imagesPropertyType?: string;
  proxyUrl?: string;
  timeout?: number;
  followRedirects?: `follow` | `error` | `manual`;
  resolveDNSHost?: (url: string) => Promise<string>;
  handleRedirects?: (baseURL: string, forwardedURL: string) => boolean;
  onResponse?: (response: ILinkPreviewResponse, doc: cheerio.Root, url?: URL) => ILinkPreviewResponse;
}

Security and Configuration

Core Types

interface ILinkPreviewResponse {
  url: string;
  title: string;
  siteName: string | undefined;
  description: string | undefined;
  mediaType: string;
  contentType: string | undefined;
  images: string[];
  videos: IVideoType[];
  favicons: string[];
  charset?: string;
}

interface IVideoType {
  url: string | undefined,
  secureUrl: string | null | undefined,
  type: string | null | undefined,
  width: string | undefined,
  height: string | undefined,
}

interface IPreFetchedResource {
  headers: Record<string, string>;
  status?: number;
  imagesPropertyType?: string;
  proxyUrl?: string;
  url: string;
  data: string;
}