link-preview-js
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.15 • Public • Published

    Link Preview JS

    npm i link-preview-js
    

    READ BEFORE CREATING AN ISSUE

    It's more than likely there is nothing wrong with the library for some simple reasons:

    • It's very simple: fetch html, parse html, look for OpenGraph html tags.
    • The library will never break unless the entire web all of the sudden decides to break itself (by changing ALL OpenGraph tags ALL AT ONCE)
    • If the target website you are trying to preview redirects you to a login page the preview will "fail"
    • If the target website does not have OpenGraph tags the preview will most likely "fail"
    • You cannot preview (read: HTTP get) another web page from YOUR web page. This is an intentional security feature of browsers called CORS

    If you haven't read this and create an issue "Amazon/Youtube/Instagram/Whatever doesn't work" I will just close the issue

    Allows you to extract information from a HTTP url/link (or parse a HTML string) and retrieve meta information such as title, description, images, videos, etc. via Facebook OpenGraph tags.

    GOTCHAs

    • You cannot request a different domain from your web app (Browsers block cross-origin-requests). If you don't know how same-origin-policy works, here is a good intro, therefore this library works on node (back-end environments) and certain mobile run-times (cordova or react-native).
    • This library acts as if the user would visit the page, sites might re-direct you to sign-up pages, consent screens, etc. You can try to change the user-agent header (try with google-bot or with Twitterbot), but you need to work around these issues yourself.
    • When you are testing this library do not use google.com, it does not return the necessary headers and you will think the library is broken.

    API

    getLinkPreview: you have to pass a string, doesn't matter if it is just a URL or a piece of text that contains a URL, the library will take care of parsing it and returning the info of first valid HTTP(S) URL info it finds.

    getPreviewFromContent: useful for passing a pre-fetched Response object from an existing async/etc. call. Refer to example below for required object values.

    import { getLinkPreview, getPreviewFromContent } from "link-preview-js";
    
    // pass the link directly
    getLinkPreview("https://www.youtube.com/watch?v=MejbOFk7H6c").then((data) =>
      console.debug(data)
    );
    
    ////////////////////////// OR //////////////////////////
    
    // pass a chunk of text
    getLinkPreview(
      "This is a text supposed to be parsed and the first link displayed https://www.youtube.com/watch?v=MejbOFk7H6c"
    ).then((data) => console.debug(data));
    
    ////////////////////////// OR //////////////////////////
    
    // pass a pre-fetched response object
    // The passed response object should include, at minimum:
    // {
    //   data: '<!DOCTYPE...><html>...',     // response content
    //   headers: {
    //     ...
    //     // should include content-type
    //     content-type: "text/html; charset=ISO-8859-1",
    //     ...
    //   },
    //   url: 'https://domain.com/'          // resolved url
    // }
    yourAjaxCall(url, (response) => {
      getPreviewFromContent(response).then((data) => console.debug(data));
    });

    Options

    Additionally you can pass an options object which should add more functionality to the parsing of the link

    Property Name Result
    imagesPropertyType (optional) (ex: 'og') Fetches images only with the specified property, meta[property='${imagesPropertyType}:image']
    headers (optional) (ex: { 'user-agent': 'googlebot', 'Accept-Language': 'en-US' }) Add request headers to fetch call
    timeout (optional) (ex: 1000) Timeout for the request to fail
    followRedirects (optional) (default false) For security reasons, the library does not automatically follow redirects, a malicious agent can exploit redirects to steal data, turn this on at your own risk
    getLinkPreview("https://www.youtube.com/watch?v=MejbOFk7H6c", {
      imagesPropertyType: "og", // fetches only open-graph images
      headers: {
        "user-agent": "googlebot" // fetches with googlebot crawler user agent
        "Accept-Language": "fr-CA", // fetches site for French language
        // ...other optional HTTP request headers
      },
      timeout: 1000
    }).then(data => console.debug(data));

    Response

    Returns a Promise that resolves with an object describing the provided link. The info object returned varies depending on the content type (MIME type) returned in the HTTP response (see below for variations of response). Rejects with an error if response can not be parsed or if there was no URL in the text provided.

    Text/HTML URL

    {
      url: "https://www.youtube.com/watch?v=MejbOFk7H6c",
      title: "OK Go - Needing/Getting - Official Video - YouTube",
      siteName: "YouTube",
      description: "Buy the video on iTunes: https://itunes.apple.com/us/album/needing-getting-bundle-ep/id508124847 See more about the guitars at: http://www.gretschguitars.com...",
      images: ["https://i.ytimg.com/vi/MejbOFk7H6c/maxresdefault.jpg"],
      mediaType: "video.other",
      contentType: "text/html; charset=utf-8",
      videos: [],
      favicons:["https://www.youtube.com/yts/img/favicon_32-vflOogEID.png","https://www.youtube.com/yts/img/favicon_48-vflVjB_Qk.png","https://www.youtube.com/yts/img/favicon_96-vflW9Ec0w.png","https://www.youtube.com/yts/img/favicon_144-vfliLAfaB.png","https://s.ytimg.com/yts/img/favicon-vfl8qSV2F.ico"]
    }

    Image URL

    {
      url: "https://media.npr.org/assets/img/2018/04/27/gettyimages-656523922nunes-4bb9a194ab2986834622983bb2f8fe57728a9e5f-s1100-c15.jpg",
      mediaType: "image",
      contentType: "image/jpeg",
      favicons: [ "https://media.npr.org/favicon.ico" ]
    }

    Audio URL

    {
      url: "https://ondemand.npr.org/anon.npr-mp3/npr/atc/2007/12/20071231_atc_13.mp3",
      mediaType: "audio",
      contentType: "audio/mpeg",
      favicons: [ "https://ondemand.npr.org/favicon.ico" ]
    }

    Video URL

    {
      url: "https://www.w3schools.com/html/mov_bbb.mp4",
      mediaType: "video",
      contentType: "video/mp4",
      favicons: [ "https://www.w3schools.com/favicon.ico" ]
    }

    Application URL

    {
      url: "https://assets.curtmfg.com/masterlibrary/56282/installsheet/CME_56282_INS.pdf",
      mediaType: "application",
      contentType: "application/pdf",
      favicons: [ "https://assets.curtmfg.com/favicon.ico" ]
    }

    License

    MIT license

    Install

    npm i link-preview-js

    DownloadsWeekly Downloads

    13,566

    Version

    2.1.15

    License

    MIT

    Unpacked Size

    31.5 kB

    Total Files

    7

    Last publish

    Collaborators

    • ospfranco