vite-plugin-favicons

0.1.7 verified Mon Apr 27 auth: no javascript

A Vite plugin that automatically generates favicons in various formats and sizes from a source image using the Favicons library. Version 0.1.7 is stable, with a moderate release cadence. It integrates seamlessly into the Vite build pipeline, provides a virtual module 'virtual:favicons' for injecting links, includes caching for faster builds, and ships TypeScript definitions. Key differentiators: designed specifically for Vite, works with SvelteKit (unlike some alternatives), and offers a simple API with optional customization via Favicons package options.

Common errors

error Error: Module 'vite-plugin-favicons' does not export a default ↓

cause Trying to import default export but the package exports named export 'faviconsPlugin'.

fix

Use import { faviconsPlugin } from 'vite-plugin-favicons' instead of import faviconsPlugin from 'vite-plugin-favicons'.

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-favicons/dist/index.js not supported. ↓

cause Using CommonJS require() to load an ESM-only package.

fix

Convert your project to ESM (add "type": "module" in package.json) or use dynamic import().

error TypeError: Cannot read properties of undefined (reading 'imgSrc') ↓

cause The plugin is called without options or with an empty object.

fix

Pass an options object with at least 'imgSrc' property, e.g., faviconsPlugin({ imgSrc: './src/assets/favicon.png' }).

error Error: The package 'favicons' is not installed. ↓

cause Missing runtime dependency 'favicons' which is required by the plugin.

fix

Install the 'favicons' package: npm install favicons.

error TS2307: Cannot find module 'virtual:favicons' or its corresponding type declarations. ↓

cause TypeScript cannot resolve the virtual module; its types are not declared.

fix

Add a declaration file (e.g., env.d.ts) with: declare module 'virtual:favicons' { const links: string; export default links; }

Warnings

breaking Plugin requires Vite >=6.3.5 and TypeScript ^5.8.3 as peer dependencies; older versions cause build errors. ↓

fix Upgrade Vite to ^6.3.5 and TypeScript to ^5.8.3.

gotcha The virtual module 'virtual:favicons' exports a default string of HTML link tags, but SvelteKit users must import { FaviconsHead } instead for proper SSR. ↓

fix In Svelte: import { FaviconsHead } from 'virtual:favicons' and use {@html FaviconsHead}. In other frameworks, import the default export.

deprecated The option 'faviconAssetsDest' may be renamed in future versions; check documentation for changes. ↓

fix Monitor release notes for option name changes.

gotcha If the source image path is incorrect or the image is missing, the plugin fails silently during build. ↓

fix Ensure imgSrc points to an existing file; verify with a console.log or check the build output.

breaking The plugin requires the 'favicons' package as a dependency; it is not bundled. Ensure it is installed. ↓

fix Run 'npm install favicons' alongside 'vite-plugin-favicons'.

gotcha The plugin does not work with CommonJS require due to ESM-only design; using require will throw a runtime error. ↓

fix Use ESM imports (import) instead of require().

Install

npm install vite-plugin-favicons

yarn add vite-plugin-favicons

pnpm add vite-plugin-favicons

Imports

faviconsPlugin

wrong

const faviconsPlugin = require('vite-plugin-favicons')

correct

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

ESM-only package; CommonJS require will fail. Use ESM imports.

Options

wrong

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

correct

import type { Options } from 'vite-plugin-favicons'

Options is a TypeScript type, not a runtime export. Use import type.

virtual:favicons (default export)
wrong
```
import { faviconLinks } from 'virtual:favicons'
```
correct
```
import faviconLinks from 'virtual:favicons'
```
The virtual module exports a default string (HTML link tags), not a named export. For Svelte, import { FaviconsHead } which is a named export.

Quickstart

Shows how to configure the plugin in vite.config.ts and use the virtual module to inject favicon links into HTML head.

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

export default defineConfig({
  plugins: [
    faviconsPlugin({
      imgSrc: './src/assets/favicon.png',
      faviconAssetsDest: 'assets/favicons',
    }),
  ],
});

// In your HTML entry: import faviconLinks from 'virtual:favicons';
// and inject into <head>

// Usage example (e.g., in a JavaScript file)
import faviconLinks from 'virtual:favicons';
document.head.insertAdjacentHTML('afterbegin', faviconLinks);