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
```