vite-plugin-favicon

1.0.8 verified Mon Apr 27 auth: no javascript

Automatically generate and manage favicons for Vite bundles from a single logo, supporting 44+ icon formats for iOS, Android, Windows Phone, and desktop browsers. Current stable version is 1.0.8 (May 2021), with infrequent releases. Partially compatible with favicons-webpack-plugin config. Ships TypeScript types. Key differentiator: minimal config, zero-config setup, and integrates with Vite's HTML plugin hooks.

Common errors

error Error: Cannot find module 'vite-plugin-favicon' ↓

cause Package not installed or not in node_modules

fix

Run 'npm install --save-dev vite-plugin-favicon'

error Error: The service you have requested is not available yet. ↓

cause The underlying favicons package may require network access to download resources (e.g., for rasterizing SVGs)

fix

Ensure you have network access or provide a pre-rasterized logo as PNG instead of SVG.

error TypeError: ViteFaviconsPlugin is not a function ↓

cause Incorrect import: using default import when named export is expected, or vice versa

fix

Use import { ViteFaviconsPlugin } from 'vite-plugin-favicon' (named export)

error Error: [vite] Internal server error: FaviconsPlugin(...).apply is not a function ↓

cause Plugin instantiated without calling it (missing parentheses) or used as Vite plugin incorrectly

fix

Ensure you call ViteFaviconsPlugin() as a function in the plugins array

Warnings

gotcha Plugin may fail silently if the logo file path is incorrect; no error is thrown for missing file in some cases. ↓

fix Always verify the logo path is correct and accessible.

deprecated The 'favicons' option directly passes config to the underlying 'favicons' package, which may change its options between versions. ↓

fix Check the favicons package documentation for available options and versions.

gotcha Plugin does not generate separate files for development; favicons are only built in production mode. ↓

fix Ensure you run a production build (vite build) to see the favicons in output.

gotcha HTML injection only works if Vite's html plugin hooks are present; if you use a custom HTML template, injection may not happen. ↓

fix Use Vite's default index.html or ensure your template includes the html plugin hooks.

gotcha The plugin generates many files (44+ icons) which can clutter the build output and increase build time. ↓

fix Consider using the 'favicons' option to limit vendors or icon sizes.

Install

npm install vite-plugin-favicon

yarn add vite-plugin-favicon

pnpm add vite-plugin-favicon

Imports

ViteFaviconsPlugin

wrong

const ViteFaviconsPlugin = require('vite-plugin-favicon')

correct

import { ViteFaviconsPlugin } from 'vite-plugin-favicon'

ESM import is the standard; CommonJS require works but not recommended for Vite projects.

ViteFaviconsPlugin (default)

wrong

import { default as ViteFaviconsPlugin } from 'vite-plugin-favicon'

correct

import ViteFaviconsPlugin from 'vite-plugin-favicon'

Plugin also has a default export, but named export is more consistent with Vite plugins.

ViteFaviconsPlugin (type)
```
import type { ViteFaviconsPlugin } from 'vite-plugin-favicon'
```
Type import is available for TypeScript usage.

Quickstart

Basic setup with a custom logo path and optional favicon configuration, demonstrating zero-config usage and TypeScript integration.

// vite.config.ts
import { defineConfig } from 'vite';
import { ViteFaviconsPlugin } from 'vite-plugin-favicon';

export default defineConfig({
  plugins: [
    ViteFaviconsPlugin('src/assets/logo.png', {
      // Optional: override default favicon generation settings
      favicons: {
        appName: 'My App',
        appShortName: 'App',
        appDescription: 'My awesome app',
        background: '#ffffff',
        theme_color: '#333333',
        display: 'standalone',
        orientation: 'portrait',
        start_url: '.',
        version: '1.0.0',
        logging: false,
        html: 'index.html',
        pipeHTML: true,
        replace: true
      }
    })
  ]
});