# serve-favicon

> favicon serving middleware with caching

Latest version **2.5.1** (published 2025-06-10) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 43/100 (D)** — status: stable.

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

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.5.1 |
| Published | 2025-06-10 |
| First published | 2014-05-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/serve-favicon) |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 5 |
| Unpacked size | 14.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 628 |
| Author | Douglas Christopher Wilson |
| Maintainers | dougwilson, ulisesgascon |
| Keywords | express, favicon, middleware |

## Links

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

## Dependencies (5)

- [ms](https://npm.io/package/ms.md) ~2.1.3
- [etag](https://npm.io/package/etag.md) ~1.8.1
- [fresh](https://npm.io/package/fresh.md) ~0.5.2
- [parseurl](https://npm.io/package/parseurl.md) ~1.3.2
- [safe-buffer](https://npm.io/package/safe-buffer.md) ~5.2.1

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 2.5.1 (latest) — 2025-06-10
- 2.5.0 — 2018-03-29
- 2.4.5 — 2017-09-26
- 2.4.4 — 2017-09-12
- 2.4.3 — 2017-05-16
- 2.4.2 — 2017-03-25
- 2.4.1 — 2017-02-28
- 2.4.0 — 2017-02-20
- 2.3.2 — 2016-11-17
- 2.3.0 — 2015-06-14
- 2.2.1 — 2015-05-14
- 2.2.0 — 2014-12-19
- 2.1.7 — 2014-11-20
- 2.1.6 — 2014-10-17
- 2.1.5 — 2014-09-24
- … 7 more at https://npm.io/package/serve-favicon/versions

## README

# serve-favicon

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Linux Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]

Node.js middleware for serving a favicon.

A favicon is a visual cue that client software, like browsers, use to identify
a site. For an example and more information, please visit
[the Wikipedia article on favicons](https://en.wikipedia.org/wiki/Favicon).

Why use this module?

  - User agents request `favicon.ico` frequently and indiscriminately, so you
    may wish to exclude these requests from your logs by using this middleware
    before your logger middleware.
  - This module caches the icon in memory to improve performance by skipping
    disk access.
  - This module provides an `ETag` based on the contents of the icon, rather
    than file system properties.
  - This module will serve with the most compatible `Content-Type`.

**Note** This module is exclusively for serving the "default, implicit favicon",
which is `GET /favicon.ico`. For additional vendor-specific icons that require
HTML markup, additional middleware is required to serve the relevant files, for
example [serve-static](https://npmjs.org/package/serve-static).

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install serve-favicon
```

## API

### favicon(path, options)

Create new middleware to serve a favicon from the given `path` to a favicon file.
`path` may also be a `Buffer` of the icon to serve.

#### Options

Serve favicon accepts these properties in the options object.

##### maxAge

The `cache-control` `max-age` directive in `ms`, defaulting to 1 year. This can
also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
module.

## Examples

Typically this middleware will come very early in your stack (maybe even first)
to avoid processing any other middleware if we already know the request is for
`/favicon.ico`.

### express

```javascript
var express = require('express')
var favicon = require('serve-favicon')
var path = require('path')

var app = express()
app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')))

// Add your routes here, etc.

app.listen(3000)
```

### connect

```javascript
var connect = require('connect')
var favicon = require('serve-favicon')
var path = require('path')

var app = connect()
app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')))

// Add your middleware here, etc.

app.listen(3000)
```

### vanilla http server

This middleware can be used anywhere, even outside express/connect. It takes
`req`, `res`, and `callback`.

```javascript
var http = require('http')
var favicon = require('serve-favicon')
var finalhandler = require('finalhandler')
var path = require('path')

var _favicon = favicon(path.join(__dirname, 'public', 'favicon.ico'))

var server = http.createServer(function onRequest (req, res) {
  var done = finalhandler(req, res)

  _favicon(req, res, function onNext (err) {
    if (err) return done(err)

    // continue to process the request here, etc.

    res.statusCode = 404
    res.end('oops')
  })
})

server.listen(3000)
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/expressjs/serve-favicon/master?label=ci
[ci-url]: https://github.com/expressjs/serve-favicon/actions/workflows/ci.yml
[coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-favicon.svg
[coveralls-url]: https://coveralls.io/r/expressjs/serve-favicon?branch=master
[downloads-image]: https://img.shields.io/npm/dm/serve-favicon.svg
[downloads-url]: https://npmjs.org/package/serve-favicon
[npm-image]: https://img.shields.io/npm/v/serve-favicon.svg
[npm-url]: https://npmjs.org/package/serve-favicon
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/serve-favicon/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/serve-favicon

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