Registry / http-networking / link-preview-js

link-preview-js

library4.0.0jsnpmunverified

link-preview-js is a JavaScript/TypeScript module designed to extract and fetch rich HTTP link information, such as title, description, images, and videos, primarily leveraging OpenGraph tags. It processes either direct URLs or text blocks containing URLs to return structured metadata. The library is currently on stable version 4.0.0 and demonstrates an active release cadence with frequent updates. A key differentiator is its explicit focus on server-side execution (Node.js >=18 environments) or specific mobile runtimes (like React Native/Cordova), strictly advising against direct client-side usage due to browser-enforced Cross-Origin Resource Sharing (CORS) policies. It also provides a utility to parse already-fetched HTML content.

http-networking web-framework data

npm install link-preview-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LINK-PREVIEW-JS

link-preview-js

http-networkingjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getLinkPreview

✓ import { getLinkPreview } from 'link-preview-js';

✗ const { getLinkPreview } = require('link-preview-js');

The library primarily uses ES Modules. For Node.js environments supporting ES Modules (>=18), use the 'import' syntax. CommonJS 'require' will not work directly.

getPreviewFromContent

✓ import { getPreviewFromContent } from 'link-preview-js';

✗ import getPreviewFromContent from 'link-preview-js';

Both `getLinkPreview` and `getPreviewFromContent` are named exports. There is no default export.

LinkPreview

✓ import type { LinkPreview } from 'link-preview-js';

For TypeScript users, import the `LinkPreview` interface for type hinting of the returned data object.

This quickstart demonstrates how to use `getLinkPreview` with both a direct URL and a text string, and `getPreviewFromContent` for pre-fetched HTML, showcasing basic usage and error handling.

import { getLinkPreview, getPreviewFromContent } from 'link-preview-js'; // Example 1: Directly fetching a link getLinkPreview('https://www.youtube.com/watch?v=MejbOFk7H6c').then((data) => { console.log('Link preview data:', data); }).catch(error => { console.error('Error fetching link preview:', error.message); }); // Example 2: Fetching from a text block const textWithLink = 'Check out this video: https://www.youtube.com/watch?v=MejbOFk7H6c and some more text.'; getLinkPreview(textWithLink).then((data) => { console.log('Link preview from text:', data); }).catch(error => { console.error('Error fetching link preview from text:', error.message); }); // Example 3: Parsing pre-fetched HTML content // In a real application, 'yourAjaxCall' would be your server-side fetch. const mockResponse = { data: '<!DOCTYPE html><html><head><title>Mock Title</title><meta property="og:description" content="Mock Description"></head><body></body></html>', headers: { 'content-type': 'text/html; charset=utf-8' }, url: 'https://example.com/mock-page' }; getPreviewFromContent(mockResponse).then((data) => { console.log('Link preview from content:', data); }).catch(error => { console.error('Error fetching link preview from content:', error.message); });

Debug

Known issues

breakingVersion 4.0.0 migrates internal URL handling to the standard WHATWG URL API. While this improves robustness and compliance, it might subtly change parsing behavior for malformed or non-standard URLs compared to previous versions. Ensure your input URLs are well-formed.

fix

Review how URLs are constructed and passed to `getLinkPreview`. Ensure they adhere to standard URL specifications. If encountering issues, validate URLs before passing them to the function.

affects: >=4.0.0

gotchaThis library is strictly intended for server-side (Node.js) or specific mobile runtime usage (e.g., React Native, Cordova). Attempting to use `getLinkPreview` directly in a browser environment will fail due to browser security policies (Cross-Origin Resource Sharing - CORS).

fix

Always run this library on your backend server. If you need link previews in a web application, implement an API endpoint on your server that calls `link-preview-js` and then serves the results to your frontend.

affects: >=1.0.0

gotchaThe preview process simulates a user visiting a page. If a target website redirects to a login page, consent screen, or another intermediary page, the library will parse that redirected content instead of the intended page, leading to incorrect preview data.

fix

Consider trying different `User-Agent` headers (e.g., 'Googlebot', 'Twitterbot') via the options object to see if the target site serves different content to known bots. However, there's no universal fix for all redirect scenarios.

affects: >=1.0.0

gotchaThe library primarily relies on OpenGraph (OG) tags for extracting metadata. If a target website does not implement OpenGraph tags, the preview will be less accurate or incomplete, despite some fallbacks.

fix

No direct fix for missing OpenGraph tags on target sites. Understand that some links may yield minimal data. You can inspect the returned data and apply custom fallbacks if certain fields are missing.

affects: >=1.0.0

breakingThe minimum required Node.js version has been updated to `^18.0.0`. Older Node.js versions are no longer supported, which might cause compatibility issues if deployed in an older environment.

fix

Ensure your Node.js environment is updated to version 18 or newer. Use `nvm` or similar tools to manage Node.js versions efficiently.

affects: >=3.0.0

Errors

Common errors & fixes

Access to fetch at 'https://example.com' from origin 'https://your-app.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Attempting to use `link-preview-js` directly in a browser environment, triggering browser security (CORS).

fix

Move `link-preview-js` usage to a backend server (Node.js) and create an API endpoint to fetch and return the preview data to your frontend.

TypeError: (0 , link_preview_js_1.getLinkPreview) is not a function

Incorrect import syntax, typically trying to use CommonJS `require` or a default import for a named export in an ESM context.

fix

Ensure you are using named imports correctly: `import { getLinkPreview } from 'link-preview-js';` and that your environment supports ESM (Node.js >=18 with appropriate `type: 'module'` in package.json or transpilation).

The link preview data is empty or incorrect, showing login page content.

The target website redirected to a login or consent page, and the library parsed that page instead of the intended content.

fix

This is a common behavior. Try passing a different `User-Agent` string in the options (e.g., mimicking a search engine bot) to see if the website serves different content. There is no guaranteed fix as websites can implement various anti-scraping measures.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/OP-Engineering/link-preview-js ↗

packagehttps://www.npmjs.com/package/link-preview-js ↗

homepagehttps://linkpreview.brianhung.com ↗