Vite Plugin Hashed Favicons

2.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that generates hashed favicons (ico, png, masked, apple-touch, web manifest) from a single optimized SVG source. Current stable version is 2.1.0 (April 2026), with frequent updates following a semver cadence. Unlike heavy favicon generators, this plugin follows the minimalist Evil Martians approach (2021) producing only essential files with content-hash filenames for cache busting. Ships TypeScript types. Requires Vite ^5.0.12 || ^6.0.0 || ^7.0.0 || ^8.0.0 as peer dependency. Key differentiator: zero runtime dependencies, SVG-only input, simplified output set.

Common errors

error Error: Could not resolve 'virtual:hashed-favicons' ↓

cause Using the virtual module without disabling injection in plugin options.

fix

Add inject: false to the favicons plugin options.

error TypeError: favicons is not a function ↓

cause Using named import instead of default import.

fix

Use import favicons from 'vite-plugin-hashed-favicons' (no curly braces).

error Module not found: Error: Can't resolve 'vite-plugin-hashed-favicons' ↓

cause Package not installed or incorrect peer dependency version.

fix

Run npm install vite-plugin-hashed-favicons and ensure Vite version is ^5.0.12 || ^6.0.0 || ^7.0.0 || ^8.0.0.

Warnings

breaking v2.0.0 replaces the `favicons` package with an own implementation, generating fewer icons and requiring SVG input only. ↓

fix Upgrade from v1: ensure source is an optimized SVG file (not PNG). Remove any options related to the old `favicons` package. Check the generated set of icons – only essential ones remain.

breaking v2.0.0 removed support for multiple favicon sizes; only 32x32 ico and standard PNG variants are produced. ↓

fix If you relied on specific sizes (e.g., 16x16, 48x48), you must generate them separately or adjust expectations.

gotcha The `inject` option defaults to true (auto-inject into HTML). If you want to use the virtual module, you must explicitly set `inject: false`. ↓

fix Set inject: false in plugin options when using virtual:hashed-favicons.

gotcha Peer dependency `vite` must satisfy either ^5.0.12, ^6.0.0, ^7.0.0, or ^8.0.0. Older or newer major versions will cause install warnings or errors. ↓

fix Ensure your project uses Vite 5, 6, 7, or 8. For Vite 4 or below, keep version 1.x or upgrade Vite.

deprecated v1.x is deprecated and no longer maintained. It relied on the external `favicons` package and had security issues with subdependencies. ↓

fix Migrate to v2.0.0+ as described in the changelog. Replace source image with SVG and adjust configuration.

Install

npm install vite-plugin-hashed-favicons

yarn add vite-plugin-hashed-favicons

pnpm add vite-plugin-hashed-favicons

Imports

favicons

wrong

import { favicons } from 'vite-plugin-hashed-favicons'

correct

import favicons from 'vite-plugin-hashed-favicons'

Default export only; named import will give undefined

virtual:hashed-favicons
wrong
```
import { favicons } from 'virtual:hashed-favicons'
```
correct
```
import favicons from 'virtual:hashed-favicons'
```
Virtual module available only when plugin option 'inject' is false. Also, add 'vite-plugin-hashed-favicons/virtual' to tsconfig types for TypeScript support.
require('vite-plugin-hashed-favicons')
```
const favicons = require('vite-plugin-hashed-favicons');
```
CommonJS require is supported. Ensure your vite config file uses CJS or .cjs extension if mixing module systems.

Quickstart

Configures Vite to generate hashed favicons from an SVG source with custom web manifest settings.

// vite.config.ts
import favicons from 'vite-plugin-hashed-favicons';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    favicons('./src/assets/favicon.svg', {
      webManifest: {
        name: 'My App',
        start_url: '/',
        display: 'standalone',
        background_color: '#ffffff',
        theme_color: '#000000',
      },
      inject: true, // default: automatically inject into HTML
    }),
  ],
});