{"id":17108,"library":"koa-favicon","title":"Koa Favicon Middleware","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/favicon","tags":["javascript","koa","middleware","favicon"],"install":[{"cmd":"npm install koa-favicon","lang":"bash","label":"npm"},{"cmd":"yarn add koa-favicon","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-favicon","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"`koa-favicon` is a Koa middleware and requires a Koa application instance to function.","package":"koa","optional":false}],"imports":[{"note":"While the official examples typically use CommonJS `require`, modern Koa applications often leverage ES Modules. This package provides compatibility for both import styles.","wrong":"const favicon = require('koa-favicon');","symbol":"favicon","correct":"import favicon from 'koa-favicon';"},{"note":"For TypeScript users, `Options` provides the interface for the middleware's configuration. Use `type` import for clarity and to avoid bundling non-runtime code.","wrong":"import { Options } from 'koa-favicon';","symbol":"Options","correct":"import { type Options } from 'koa-favicon';"}],"quickstart":{"code":"import Koa from 'koa';\nimport favicon from 'koa-favicon';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst app = new Koa();\nconst port = 3000;\n\n// Ensure you have a 'favicon.ico' file in a 'public' directory next to your app entry file.\n// For example: my-app/public/favicon.ico\napp.use(favicon(path.join(__dirname, 'public', 'favicon.ico'), {\n  maxAge: 1000 * 60 * 60 * 24 * 7 // Cache for 7 days\n}));\n\napp.use(async (ctx) => {\n  ctx.body = 'Hello, Koa favicon example!';\n});\n\napp.listen(port, () => {\n  console.log(`Koa application listening on http://localhost:${port}`);\n  console.log('Try accessing http://localhost:3000/favicon.ico directly in your browser or developer tools.');\n});","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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).","severity":"breaking","affected_versions":"<2.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you multiply your desired duration in seconds by `1000`. For example, `1000 * 60 * 60 * 24` sets the `maxAge` for one full day.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The specified path to the `favicon.ico` file is incorrect or the file does not exist at that location.","error":"Error: ENOENT: no such file or directory, stat '/path/to/your/app/favicon.ico'"},{"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.","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.","error":"TypeError: app.use is not a function"}],"ecosystem":"npm","meta_description":null}