Install

1npm install --dev-save @openscript/unplugin-favicons favicons

1yarn add -D @openscript/unplugin-favicons favicons

1pnpm add -D @openscript/unplugin-favicons favicons

Zero Config Usage

Add your base logo as logo.png file to your assets folder.

Only declared icons generation

1unpluginFavicons({
2    /**
3     * Specify each icon type to render. Unlike `favicons`, this plugin is
4     * opt-in, meaning only the icon types you declare here will be rendered.
5     *
6     * For each icon type, all `favicons` options are supported. An
7     * additional `source` property is required to indicate the asset to be
8     * used for that icon type.
9     */
10    icons: {
11        favicons: {
12            source: "./assets/favicon.png",
13        },
14        android: {
15            source: "./assets/android.png",
16        },
17        appleStartup: {
18            source: "./assets/apple-startup.png",
19        },
20    },
21});

Add the plugin to your bundler as follow:

1// vite.config.ts
2import unpluginFavicons from "@openscript/unplugin-favicons/vite";
3
4export default defineConfig({
5    plugins: [
6        unpluginFavicons({
7            /* options */
8        }),
9    ],
10});

1// rollup.config.js
2import unpluginFavicons from "@openscript/unplugin-favicons/rollup";
3// To use the auto inject
4import html from "@rollup/plugin-html";
5
6export default {
7    plugins: [
8        // html(), // optional
9        unpluginFavicons({
10            /* options */
11        }),
12    ],
13};

1// esbuild.config.js
2import { build } from "esbuild";
3
4build({
5    plugins: [
6        require("@openscript/unplugin-favicons/esbuild")({
7            /* options */
8        }),
9    ],
10});

1// webpack.config.js
2module.exports = {
3    /* ... */
4    plugins: [
5        require("@openscript/unplugin-favicons/webpack")({
6            /* options */
7        }),
8    ],
9};

1// vue.config.js
2module.exports = {
3    configureWebpack: {
4        plugins: [
5            require("@openscript/unplugin-favicons/webpack")({
6                /* options */
7            }),
8        ],
9    },
10};

1// nuxt.config.js
2export default {
3    buildModules: [
4        [
5            "@openscript/unplugin-favicons/nuxt",
6            {
7                /* options */
8            },
9        ],
10    ],
11};

1// nuxt.config.js
2export default defineNuxtConfig({
3    modules: [
4        [
5            "@openscript/unplugin-favicons/nuxt",
6            {
7                /* options */
8            },
9        ],
10    ],
11});

1// vite.config.js
2import { defineConfig } from "vite";
3import { sveltekit } from "@sveltejs/kit/vite";
4import unpluginFavicons from "@openscript/unplugin-favicons/vite";
5
6export default defineConfig({
7    plugins: [
8        sveltekit(),
9        unpluginFavicons({
10            /* options */
11        }),
12    ],
13});

1import { metadata } from "@openscript/unplugin-favicons/runtime"; // use default import
2import type { Handle } from "@sveltejs/kit";
3
4export const handle: Handle = async ({ event, resolve }) => {
5    const response = await resolve(event, {
6        transformPageChunk: ({ html }) => html.replace("</head>", `${metadata}</head>`),
7    });
8    return response;
9};

1npm i -D @sveltejs/vite-plugin-svelte

1// vite.config.js
2import { defineConfig } from "vite";
3import { svelte } from "@sveltejs/vite-plugin-svelte";
4import unpluginFavicons from "@openscript/unplugin-favicons/vite";
5
6export default defineConfig({
7    plugins: [
8        svelte(),
9        unpluginFavicons({
10            /* options */
11        }),
12    ],
13});

1/** @type {import('next').NextConfig} */
2module.exports = {
3    reactStrictMode: true,
4    webpack(config) {
5        config.plugins.push(
6            require("@openscript/unplugin-favicons/webpack")({
7                /* options */
8            }),
9        );
10
11        return config;
12    },
13};

1// astro.config.mjs
2import { defineConfig } from "astro/config";
3import unpluginFavicons from "@openscript/unplugin-favicons/vite";
4
5// https://astro.build/config
6export default defineConfig({
7    vite: {
8        plugins: [
9            unpluginFavicons({
10                /* options */
11            }),
12        ],
13    },
14});

The default configuration will automatically generate webapp manifest files along with 44 different icon formats as appropriate for iOS devices, Android devices, Windows Phone and various desktop browsers out of your single logo.png.

Tip: You might want to fine tune what vendors to support.

A Note on Path Resolution

Under the hood, Vite/Rollup resolve the paths to the logo and favicons according to the following rules:

• If /path/to/logo is absolute, there is nothing to resolve and the path specified is used as is.

• If ./path/to/logo is relative, it’s resolved with respect to process.cwd().

HTML Injection

In combination with Vite’s html plugin hooks it will also inject the necessary html for you:

1<link rel="apple-touch-icon" sizes="57x57" href="/assets/apple-touch-icon-57x57.png" />
2<link rel="apple-touch-icon" sizes="60x60" href="/assets/apple-touch-icon-60x60.png" />
3<link rel="apple-touch-icon" sizes="72x72" href="/assets/apple-touch-icon-72x72.png" />
4<link rel="apple-touch-icon" sizes="76x76" href="/assets/apple-touch-icon-76x76.png" />
5<link rel="apple-touch-icon" sizes="114x114" href="/assets/apple-touch-icon-114x114.png" />
6<link rel="apple-touch-icon" sizes="120x120" href="/assets/apple-touch-icon-120x120.png" />
7<link rel="apple-touch-icon" sizes="144x144" href="/assets/apple-touch-icon-144x144.png" />
8<link rel="apple-touch-icon" sizes="152x152" href="/assets/apple-touch-icon-152x152.png" />
9<link rel="apple-touch-icon" sizes="167x167" href="/assets/apple-touch-icon-167x167.png" />
10<link rel="apple-touch-icon" sizes="180x180" href="/assets/apple-touch-icon-180x180.png" />
11<link rel="apple-touch-icon" sizes="1024x1024" href="/assets/apple-touch-icon-1024x1024.png" />
12<link
13    rel="apple-touch-startup-image"
14    media="(device-width: 320px) and (device-height: 480px) and (-webkit-device-pixel-ratio: 1)"
15    href="/assets/apple-touch-startup-image-320x460.png"
16/>
17<link
18    rel="apple-touch-startup-image"
19    media="(device-width: 320px) and (device-height: 480px) and (-webkit-device-pixel-ratio: 2)"
20    href="/assets/apple-touch-startup-image-640x920.png"
21/>
22<link
23    rel="apple-touch-startup-image"
24    media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)"
25    href="/assets/apple-touch-startup-image-640x1096.png"
26/>
27<link
28    rel="apple-touch-startup-image"
29    media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)"
30    href="/assets/apple-touch-startup-image-750x1294.png"
31/>
32<link
33    rel="apple-touch-startup-image"
34    media="(device-width: 414px) and (device-height: 736px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 3)"
35    href="/assets/apple-touch-startup-image-1182x2208.png"
36/>
37<link
38    rel="apple-touch-startup-image"
39    media="(device-width: 414px) and (device-height: 736px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 3)"
40    href="/assets/apple-touch-startup-image-1242x2148.png"
41/>
42<link
43    rel="apple-touch-startup-image"
44    media="(device-width: 768px) and (device-height: 1024px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 1)"
45    href="/assets/apple-touch-startup-image-748x1024.png"
46/>
47<link
48    rel="apple-touch-startup-image"
49    media="(device-width: 768px) and (device-height: 1024px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 2)"
50    href="/assets/apple-touch-startup-image-1496x2048.png"
51/>
52<link
53    rel="apple-touch-startup-image"
54    media="(device-width: 768px) and (device-height: 1024px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 1)"
55    href="/assets/apple-touch-startup-image-768x1004.png"
56/>
57<link
58    rel="apple-touch-startup-image"
59    media="(device-width: 768px) and (device-height: 1024px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 2)"
60    href="/assets/apple-touch-startup-image-1536x2008.png"
61/>
62<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16x16.png" />
63<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32x32.png" />
64<link rel="icon" type="image/png" sizes="228x228" href="/assets/coast-228x228.png" />
65<link rel="manifest" href="/assets/manifest.json" />
66<link rel="shortcut icon" href="/assets/favicon.ico" />
67<link rel="yandex-tableau-widget" href="/assets/yandex-browser-manifest.json" />
68<meta name="apple-mobile-web-app-capable" content="yes" />
69<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
70<meta name="apple-mobile-web-app-title" />
71<meta name="application-name" />
72<meta name="mobile-web-app-capable" content="yes" />
73<meta name="msapplication-TileColor" content="#fff" />
74<meta name="msapplication-TileImage" content="/assets/mstile-144x144.png" />
75<meta name="msapplication-config" content="/assets/browserconfig.xml" />
76<meta name="theme-color" content="#fff" />

Advanced Usage

1  unpluginFavicons({
2    /** Your source logo (Will default to ) */
3    logo?: "assets/logo.png",
4    /** Inject html links/metadata. */
5    inject?: true,
6    /** `Favicons` configuration options
7    *  - [See `favicons` documentation](https://github.com/itgalaxy/favicons) */
8    favicons?: FaviconsConfig,
9    /** The root of the project from which you want to load metadata */
10    projectRoot?: process.cwd(),
11  })

To fine tune what icons/metadata is generated, refer to favicons’ documentation.

The options specified under favicons: are handed over as is to [favicons], except that if appName, appDescription, version, developerName or developerURL are left undefined, they will be automatically inferred respectively from name, description, version, author.name and author.url as defined in the nearest package.json if available. And if there’s no author it will use the first in the contributors. To disable automatically retrieving metadata from package.json, set to null the properties you want to omit.

Examples

Basic

1unpluginFavicons({
2    logo: "./src/logo.png", // svg works too!
3    favicons: {
4        appName: "my-app",
5        appDescription: "My awesome App",
6        developerName: "Me",
7        developerURL: null, // prevent retrieving from the nearest package.json
8        background: "#ddd",
9        theme_color: "#333",
10        icons: {
11            coast: false,
12            yandex: false,
13        },
14    },
15});

To fine tune what icons/metadata is generated, refer to favicons’ documentation.

Handling Multiple HTML Files

Vite calls the HTML transform hook for each HTML file template file you have configured in Vite, so this works automatically.

Runtime

The @openscript/unplugin-favicons plugin also exports a runtime module that can be used to inject the generated metadata into your HTML files or access the files and images used in the metadata.

1import { metadata, images, files } from "@openscript/unplugin-favicons/runtime";
2
3console.log(metadata, images, files);

Changelog

Take a look at the CHANGELOG.md.

Contribution

You’re free to contribute to this project by submitting issues and/or pull requests.

Please keep in mind that every change and feature should be covered by tests.

License

This project is licensed under MIT.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• Daniel Bannert
• All Contributors

License

The anolilab vite-plugin-favicon is open-sourced software licensed under the MIT license