# favicon-thief

> Find the best favicon for a given URL.

Latest version **2.1.0** (published 2023-01-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install favicon-thief
pnpm add favicon-thief
yarn add favicon-thief
bun add favicon-thief
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2023-01-25 |
| First published | 2022-10-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16 |
| Dependencies | 3 |
| Unpacked size | 827.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Maintainers | kamilmielnik, yuriyyakym |
| Keywords | favicon, thief, download, fetch, best, largest, image, file |

## Links

- npm: https://www.npmjs.com/package/favicon-thief
- Repository: https://github.com/limesquid/favicon-thief
- Homepage: https://github.com/limesquid/favicon-thief#readme
- Issues: https://github.com/limesquid/favicon-thief/issues
- npm.io page: https://npm.io/package/favicon-thief

## Dependencies (3)

- [puppeteer](https://npm.io/package/puppeteer.md) ^19.6.0
- [validator](https://npm.io/package/validator.md) ^13.7.0
- [url-toolkit](https://npm.io/package/url-toolkit.md) ^2.2.5

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 2.1.0 (latest) — 2023-01-25
- 2.1.0-beta.0 (next) — 2023-01-25
- 2.0.4-beta.0 — 2023-01-25
- 2.0.3 — 2023-01-25
- 2.0.2 — 2023-01-25
- 2.0.1 — 2023-01-25
- 2.0.0 — 2022-12-12
- 1.1.1 — 2022-12-08
- 1.1.0 — 2022-12-08
- 1.0.0 — 2022-10-07
- 1.0.0-rc.0 — 2022-10-07

## README

# favicon-thief

Find the best favicon for a given URL.

Powers [https://websktop.com](https://websktop.com).

![Version](https://img.shields.io/github/package-json/v/limesquid/favicon-thief)
![License](https://img.shields.io/npm/l/favicon-thief)
![Node version](https://img.shields.io/node/v/favicon-thief)
![Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/limesquid/favicon-thief)
![Build](https://github.com/limesquid/favicon-thief/workflows/Build/badge.svg)
![Test](https://github.com/limesquid/favicon-thief/workflows/Test/badge.svg)
![Prettier](https://github.com/limesquid/favicon-thief/workflows/Prettier/badge.svg)

# Installation

```Shell
npm install favicon-thief --save
```

# API

## `getFavicons`

Uses [`findFavicons`](#findfavicons) to get all favicons that represent given URL. Uses [node-fetch](https://github.com/node-fetch/node-fetch) & [puppeteer](https://github.com/puppeteer/puppeteer) to crawl webpages.

- Results are sorted - best first.
- Favors vector images, square images, and large images (in that order).

It's a wrapper for [`findFavicons`](#findfavicons) that provides [`fetch`](https://github.com/limesquid/favicon-thief/pull/25/files#diff-eaacc35d5a5d88d1ede34aa0d4e69ca13c836d6e7702357865a70b2aba584880R22) implementations.

```ts
import { getFavicons } from 'favicon-thief';

const favicons = await getFavicons('https://websktop.com');

console.log(JSON.stringify(favicons, null, 2));
// [
//   {
//     "sizes": [
//       {
//         "width": 144,
//         "height": 144
//       }
//     ],
//     "source": "html",
//     "url": "https://www.youtube.com/s/desktop/25bf5aae/img/favicon_144x144.png"
//   },
//   {
//     "sizes": [
//       {
//         "width": 96,
//         "height": 96
//       }
//     ],
//     "source": "html",
//     "url": "https://www.youtube.com/s/desktop/25bf5aae/img/favicon_96x96.png"
//   },
//   {
//     "sizes": [
//       {
//         "width": 48,
//         "height": 48
//       }
//     ],
//     "source": "html",
//     "url": "https://www.youtube.com/s/desktop/25bf5aae/img/favicon_48x48.png"
//   },
//   {
//     "sizes": [
//       {
//         "width": 32,
//         "height": 32
//       }
//     ],
//     "source": "html",
//     "url": "https://www.youtube.com/s/desktop/25bf5aae/img/favicon_32x32.png"
//   },
//   {
//     "sizes": [],
//     "source": "html",
//     "url": "https://www.youtube.com/s/desktop/25bf5aae/img/favicon.ico"
//   },
//   {
//     "sizes": [],
//     "source": "guess",
//     "url": "https://www.youtube.com/favicon.ico"
//   },
//   {
//     "sizes": [],
//     "source": "guess",
//     "url": "https://youtube.com/favicon.ico"
//   }
// ]
```

## `findFavicons`

Finds all favicons that represent given URL.

- Pass your own fetching function.
- Results are sorted - best first.
- Favors vector images, square images, and large images (in that order).
- It never throws.

```ts
import { findFavicons } from 'favicon-thief';

const myFetch = async (url: string): string => {
  // bring your own fetching implementation - turn `url` into html here
  return {
    data: '<html><head><link rel="icon" href="icon.png" sizes="160x160"></head></html>',
    url, // return different url if there was a redirect
  };
};

const favicons = await findFavicons('http://example.com', myFetch);

console.log(JSON.stringify(favicons, null, 2));
// [
//   {
//     "sizes": [
//       {
//         "width": 160,
//         "height": 160
//       }
//     ],
//     "source": "html",
//     "url": "http://example.com/icon.png"
//   },
//   {
//     "sizes": [],
//     "source": "guess",
//     "url": "http://example.com/favicon.ico"
//   }
// ]
```

---
_Source: https://npm.io/package/favicon-thief · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._