Registry / web-framework / vite-plugin-favicons

vite-plugin-favicons

library0.1.7jsnpmunverified

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.

web-framework

npm install vite-plugin-favicons

package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-FAVICO

vite-plugin-favicons

web-frameworkjavascriptv0.1.7

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–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

faviconsPlugin

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

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

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

Options

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

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

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

virtual:favicons (default export)

✓ import faviconLinks from 'virtual:favicons'

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

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);

Debug

Known issues

breakingPlugin 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.

affects: <0.1.7

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

affects: >=0.1.0

deprecatedThe option 'faviconAssetsDest' may be renamed in future versions; check documentation for changes.

fix

Monitor release notes for option name changes.

affects: >=0.1.0

gotchaIf 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.

affects: >=0.1.0

breakingThe 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'.

affects: >=0.1.0

gotchaThe 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().

affects: >=0.1.0

Errors

Common errors & fixes

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

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 [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-favicons/dist/index.js not supported.

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

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

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: The package 'favicons' is not installed.

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

fix

Install the 'favicons' package: npm install favicons.

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

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; }

Upgrade

Version history

0.1.7latest on npm

Audit

Dependencies

faviconsrequiredCore dependency for generating favicons from source image.

viterequiredPeer dependency - plugin only works with Vite >=6.3.5.

typescriptoptionalPeer dependency for TypeScript type definitions - required for TS projects.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vite-plugin-favicons ↗