koa-favicon

library2.1.0jsnpmunverified

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.

web-framework

npm install koa-favicon

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-FAVICON

koa-favicon

web-frameworkjavascriptv2.1.0

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

✓ import favicon from 'koa-favicon';

✗ const favicon = require('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

✓ import { type Options } from 'koa-favicon';

✗ import { 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.

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

Debug

Known issues

breakingOlder 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`.

affects: <2.0.0

gotchaIncorrect 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).

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, stat '/path/to/your/app/favicon.ico'

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

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.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

koarequired`koa-favicon` is a Koa middleware and requires a Koa application instance to function.

Agent activity

3 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/koajs/favicon ↗

packagehttps://www.npmjs.com/package/koa-favicon ↗