0
# Link Preview JS
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: link-preview-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install link-preview-js`
10
11
## Core Imports
12
13
```typescript
14
import { getLinkPreview, getPreviewFromContent } from "link-preview-js";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { getLinkPreview, getPreviewFromContent } = require("link-preview-js");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { getLinkPreview } from "link-preview-js";
27
28
// Extract preview from URL
29
const preview = await getLinkPreview("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
30
31
console.log(preview.title); // "Rick Astley - Never Gonna Give You Up"
32
console.log(preview.description); // Video description
33
console.log(preview.images[0]); // Thumbnail URL
34
console.log(preview.siteName); // "YouTube"
35
36
// Extract from text containing URL
37
const textPreview = await getLinkPreview(
38
"Check out this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
39
);
40
41
// With custom options
42
const customPreview = await getLinkPreview("https://example.com", {
43
headers: { "User-Agent": "MyBot/1.0" },
44
timeout: 5000,
45
followRedirects: "follow"
46
});
47
```
48
49
## Architecture
50
51
Link Preview JS is built around several key components:
52
53
- **URL Detection**: Automatic URL extraction from text using regex patterns with security validations
54
- **HTTP Client**: Built-in fetch with configurable timeouts, headers, and redirect handling
55
- **HTML Parser**: Cheerio-based DOM parsing for extracting metadata from various tag types
56
- **Content Type Handler**: Specialized parsers for different media types (HTML, images, audio, video, applications)
57
- **Security Layer**: SSRF protection through DNS resolution validation and private IP blocking
58
- **Metadata Extraction**: Multi-source extraction from OpenGraph, Twitter Cards, and standard HTML meta tags
59
60
## Capabilities
61
62
### Link Preview Extraction
63
64
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.
65
66
```typescript { .api }
67
function getLinkPreview(
68
text: string,
69
options?: ILinkPreviewOptions
70
): Promise<ILinkPreviewResponse>;
71
```
72
73
[Link Preview Extraction](./link-preview.md)
74
75
### Pre-fetched Content Processing
76
77
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.
78
79
```typescript { .api }
80
function getPreviewFromContent(
81
response: IPreFetchedResource,
82
options?: ILinkPreviewOptions
83
): Promise<ILinkPreviewResponse>;
84
```
85
86
[Pre-fetched Content Processing](./pre-fetched-content.md)
87
88
### Security and Configuration
89
90
Advanced security features and configuration options for customizing request behavior, handling redirects, and preventing SSRF attacks through DNS resolution validation.
91
92
```typescript { .api }
93
interface ILinkPreviewOptions {
94
headers?: Record<string, string>;
95
imagesPropertyType?: string;
96
proxyUrl?: string;
97
timeout?: number;
98
followRedirects?: `follow` | `error` | `manual`;
99
resolveDNSHost?: (url: string) => Promise<string>;
100
handleRedirects?: (baseURL: string, forwardedURL: string) => boolean;
101
onResponse?: (response: ILinkPreviewResponse, doc: cheerio.Root, url?: URL) => ILinkPreviewResponse;
102
}
103
```
104
105
[Security and Configuration](./security-configuration.md)
106
107
## Core Types
108
109
```typescript { .api }
110
interface ILinkPreviewResponse {
111
url: string;
112
title: string;
113
siteName: string | undefined;
114
description: string | undefined;
115
mediaType: string;
116
contentType: string | undefined;
117
images: string[];
118
videos: IVideoType[];
119
favicons: string[];
120
charset?: string;
121
}
122
123
interface IVideoType {
124
url: string | undefined,
125
secureUrl: string | null | undefined,
126
type: string | null | undefined,
127
width: string | undefined,
128
height: string | undefined,
129
}
130
131
interface IPreFetchedResource {
132
headers: Record<string, string>;
133
status?: number;
134
imagesPropertyType?: string;
135
proxyUrl?: string;
136
url: string;
137
data: string;
138
}
139
```