Registry / web-framework / serve-favicon

serve-favicon

JSON →
library2.5.1jsnpmunverified

serve-favicon is a Node.js middleware designed for efficiently serving the `favicon.ico` file in web applications, primarily within the Express.js and Connect.js ecosystems. Currently at version 2.5.1, this package is actively maintained, receiving updates primarily for dependency management and CI improvements, rather than frequent feature additions. Its core purpose is to optimize favicon delivery by caching the icon in memory, generating robust ETags based on file content, and correctly setting the `Content-Type` header. A key differentiator is its specific focus on the default `/favicon.ico` path, ensuring that these high-frequency requests are handled quickly and bypass subsequent middleware in the stack, thereby improving overall application performance by reducing unnecessary processing for static assets.

web-frameworkhttp-networking
npm install serve-favicon
github ↗package ↗
INSTALL
IMPORT
SIG · SERVE-FAVICON
S
serve-favicon
web-frameworkjavascriptv2.5.1
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.

favicon
✓ const favicon = require('serve-favicon')
✗ import favicon from 'serve-favicon'
This package is CommonJS-only and does not provide an ESM export.
faviconMiddleware
✓ const favicon = require('serve-favicon')
✗ import { faviconMiddleware } from 'serve-favicon'
The module exports a single function; there are no named exports. Aliasing the import variable is common.
options
✓ favicon(path.join(__dirname, 'public', 'favicon.ico'), { maxAge: '1d' })
✗ favicon(path.join(__dirname, 'public', 'favicon.ico'), { maxAge: 86400000 })
The `maxAge` option accepts either a number (milliseconds) or a string parseable by the `ms` library (e.g., '1h', '30d').

This example sets up a basic Express server, uses `serve-favicon` to serve a favicon from a 'public' directory, and includes logic to create a dummy favicon file if one doesn't exist, making the example runnable out-of-the-box.

const express = require('express'); const favicon = require('serve-favicon'); const path = require('path'); const fs = require('fs'); const app = express(); const publicDir = path.join(__dirname, 'public'); const faviconPath = path.join(publicDir, 'favicon.ico'); // Ensure the 'public' directory exists if (!fs.existsSync(publicDir)) { fs.mkdirSync(publicDir); } // Create a dummy favicon.ico if it doesn't exist for the example to run if (!fs.existsSync(faviconPath)) { // A minimal, valid ICO file (1x1 transparent pixel) const dummyFavicon = Buffer.from('0000010001001010000001000400000028000000010000000100000001000400000000001600000000000000000000000000000000000000', 'hex'); fs.writeFileSync(faviconPath, dummyFavicon); } // Use serve-favicon middleware // It should be placed early in your middleware stack app.use(favicon(faviconPath, { maxAge: '30d' })); app.get('/', (req, res) => { res.send('Hello from your Express app with a favicon!'); }); app.listen(3000, () => { console.log('Server running on http://localhost:3000'); });
Debug
Known issues
gotchaThe `serve-favicon` middleware is exclusively designed to serve the default `GET /favicon.ico` request. It will not handle other vendor-specific icons (e.g., Apple Touch Icons, Web App Manifest icons) which typically require specific HTML markup and other static file serving middleware like `serve-static`.
fix
For additional icon types, use `serve-static` or similar middleware to serve those files from their expected paths, in conjunction with appropriate HTML `<link>` tags.
affects: >=1.0.0
gotchaTo ensure optimal performance and prevent unnecessary processing, `serve-favicon` should be placed very early in your middleware stack, ideally before any logger or heavy processing middleware. This allows `favicon.ico` requests to be handled and responded to quickly.
fix
Order your middleware such that `app.use(favicon(...))` appears before `app.use(logger(...))` or other route handlers.
affects: >=1.0.0
gotchaThe package currently uses CommonJS modules (`require`) and does not natively support ES Modules (`import`). Attempting to use `import` syntax will result in a runtime error.
fix
Always use `const favicon = require('serve-favicon');` to import the module in Node.js applications.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: favicon is not a function
Attempting to use ES module `import` syntax or destructuring when the package is CommonJS-only.
fix
Change `import favicon from 'serve-favicon'` to `const favicon = require('serve-favicon')`.
Cannot GET /favicon.ico
The favicon file path provided to `serve-favicon` is incorrect, or the middleware is placed too late in the stack after other handlers have already consumed the request.
fix
Double-check the `path.join(__dirname, 'public', 'favicon.ico')` argument to ensure it points to an existing file. Ensure `app.use(favicon(...))` is placed early in your Express/Connect middleware chain.
favicon not showing or slow to load
Caching issues (e.g., `maxAge` set too low or browser cache) or the middleware being placed after a logger that's delaying the response.
fix
Adjust the `maxAge` option for aggressive caching (e.g., `{ maxAge: '30d' }`). Verify `serve-favicon` is positioned before any logging middleware like `morgan` to prevent unnecessary logging of favicon requests and ensure quick responses.
Upgrade
Version history
2.5.1latest on npm
Audit
Dependencies
msrequiredUsed internally and for the `maxAge` option to parse time strings.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
githubhttps://github.com/expressjs/serve-favicon ↗
packagehttps://www.npmjs.com/package/serve-favicon ↗
serve-favicon — npm install serve-favicon · libregistry