Koa Favicon Middleware

2.1.0 · active · verified Wed Apr 22

This middleware for Koa applications efficiently serves a `favicon.ico` file, handling requests for `/favicon.ico` and setting appropriate cache headers. Built upon the proven `serve-favicon` package, it provides a straightforward way to integrate favicon serving directly into the Koa middleware stack. The current stable version is 2.1.0, a mature release from the Koa organization. Its release cadence is generally slow, primarily responding to Koa framework updates or critical maintenance. It differentiates itself by its minimalistic API and direct compatibility with Koa's `app.use()` pattern, making it a standard choice for basic favicon serving in Koa projects. It supports custom `maxAge` caching and MIME type specification.

Common errors

```
Error: ENOENT: no such file or directory, stat '/path/to/your/app/favicon.ico'
```
cause The specified path to the `favicon.ico` file is incorrect or the file does not exist at that location.

fix Double-check the absolute path provided to the `favicon()` middleware. Verify the file's existence and correct its path using `path.join` for robustness, especially with different environments.
```
TypeError: app.use is not a function
```
cause This error indicates that the `app` object is not a valid Koa application instance, or you might be using an extremely outdated Koa setup.

fix Ensure you are correctly importing Koa (`import Koa from 'koa';`) and instantiating it with `const app = new Koa();`. This error is rare in modern Koa environments.

Warnings

breaking Older versions of `koa-favicon` (pre-v2.0.0) are designed for Koa v1 (generator-based middleware) and are incompatible with Koa v2+ (async/await-based).
Fix: Upgrade `koa-favicon` to version `2.x` for compatibility with Koa v2+ applications using `async/await`. If you are specifically targeting Koa v1, use `koa-favicon@^1.0.0`.
gotcha Incorrect or relative file paths for `favicon.ico` are a common source of errors, resulting in a 404 for `/favicon.ico` requests or the favicon not being served.
Fix: Always use `path.join(__dirname, 'your_directory', 'favicon.ico')` to construct an absolute and robust path, ensuring the file exists at the specified location relative to your application's entry point. When using ES Modules, `__dirname` needs to be derived (as shown in the quickstart).
gotcha The `maxAge` option for cache control is specified in milliseconds, not seconds. A common mistake is to provide a value like `3600` expecting an hour, but it will only cache for 3.6 seconds.
Fix: Ensure you multiply your desired duration in seconds by `1000`. For example, `1000 * 60 * 60 * 24` sets the `maxAge` for one full day.

Install

npm install koa-favicon npm
yarn add koa-favicon yarn
pnpm add koa-favicon pnpm

Imports

favicon
wrong:
```
const favicon = require('koa-favicon');
```
correct:
```
import favicon from 'koa-favicon';
```
While the official examples typically use CommonJS `require`, modern Koa applications often leverage ES Modules. This package provides compatibility for both import styles.
Options
wrong:
```
import { Options } from 'koa-favicon';
```
correct:
```
import { type Options } from 'koa-favicon';
```
For TypeScript users, `Options` provides the interface for the middleware's configuration. Use `type` import for clarity and to avoid bundling non-runtime code.

Quickstart

This example demonstrates setting up a basic Koa application to serve a favicon from a specified path with a 7-day cache, showcasing typical usage with ES Modules.

import Koa from 'koa';
import favicon from 'koa-favicon';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const app = new Koa();
const port = 3000;

// Ensure you have a 'favicon.ico' file in a 'public' directory next to your app entry file.
// For example: my-app/public/favicon.ico
app.use(favicon(path.join(__dirname, 'public', 'favicon.ico'), {
  maxAge: 1000 * 60 * 60 * 24 * 7 // Cache for 7 days
}));

app.use(async (ctx) => {
  ctx.body = 'Hello, Koa favicon example!';
});

app.listen(port, () => {
  console.log(`Koa application listening on http://localhost:${port}`);
  console.log('Try accessing http://localhost:3000/favicon.ico directly in your browser or developer tools.');
});

view raw JSON →