Serve Favicon Middleware

Common errors

• TypeError: favicon is not a function

  cause 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

  cause 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

  cause 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.

Warnings

• gotcha The `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.
• gotcha To 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.
• gotcha The 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.

Install

• npm install serve-favicon npm
• yarn add serve-favicon yarn
• pnpm add serve-favicon pnpm

Imports

• favicon
  wrong:

  import favicon from 'serve-favicon'

  correct:

  const favicon = require('serve-favicon')

  This package is CommonJS-only and does not provide an ESM export.
• faviconMiddleware
  wrong:

  import { faviconMiddleware } from 'serve-favicon'

  correct:

  const favicon = require('serve-favicon')

  The module exports a single function; there are no named exports. Aliasing the import variable is common.
• options
  wrong:

  favicon(path.join(__dirname, 'public', 'favicon.ico'), { maxAge: 86400000 })

  correct:

  favicon(path.join(__dirname, 'public', 'favicon.ico'), { maxAge: '1d' })

  The `maxAge` option accepts either a number (milliseconds) or a string parseable by the `ms` library (e.g., '1h', '30d').

Quickstart

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');
});