# Favicons Vite Plugin
This is a fork of [josh-hemphill/vite-plugin-favicon](https://github.com/josh-hemphill/vite-plugin-favicon). It was forked and published on npm under vite-plugin-favicon2 in order to address the following issues/features:
* [#1](https://github.com/josh-hemphill/vite-plugin-favicon/issues/1) - Doesn't appear to work in dev mode
* [#3](https://github.com/josh-hemphill/vite-plugin-favicon/issues/3) - Allow vite-plugin-favicon to save the HTML to a file
* Un-deprecated the `outputPath` config setting, to allow you to specify where the output assets are saved, relative to the Vite assets directory
Install with:
```
npm install --save-dev vite-plugin-favicon2
```
Add the plugin to your vite config as follows:
```javascript
const ViteFaviconsPlugin = require('vite-plugin-favicon2')
// or ESM
import { ViteFaviconsPlugin } from "vite-plugin-favicon2";
```
...and then add to your `vite.config.js`:
```javascript
plugins: [
ViteFaviconsPlugin({
/** Your source logo (Will default to )
@default "assets/logo.png"
*/
logo?: string,
/** Inject html links/metadata -- set to `false` to generate a webapp.html` file.
@default true
*/
inject?: boolean,
/** `Favicons` configuration options
* - [See `favicons` documentation](https://github.com/itgalaxy/favicons)
*/
favicons?: FaviconsConfig,
/** The root of the project from which you want to load metadata
@default process.cwd()
*/
projectRoot?: string,
/** Output Path for the favicon images & files, relative to the Vite assets directory
*/
outputPath?: string,
/** prefix is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated
*/
prefix?: string,
/** Caching is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated
*/
cache?: boolean,
/** Public Path is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated
*/
publicPath?: string,
})
]
```
The original README.md follows, unmodified:
-----
Leverages on [favicons](https://github.com/haydenbleasel/favicons) to automatically generate your favicons for you.
And if you want to also consolidate your PWA manifest, will generate that as well with linked icons.
Partially adapted from and config compatible with [favicons-webpack-plugin](https://github.com/jantimon/favicons-webpack-plugin)
## Installation
Install the plugin with npm:
```shell
$ npm install --save-dev vite-plugin-favicon
# Or shorthand
npm i -D vite-plugin-favicon
```
## Zero Config Usage
Add your base logo as `logo.png` file to your assets folder.
Add the plugin to your vite config as follows:
```javascript
const ViteFaviconsPlugin = require('vite-plugin-favicon')
// or ESM
import { ViteFaviconsPlugin } from 'vite-plugin-favicon';
plugins: [
ViteFaviconsPlugin()
]
```
## Basic Usage
Add the plugin to your vite config as follows:
```javascript
const ViteFaviconsPlugin = require('vite-plugin-favicon')
// or ESM
import { ViteFaviconsPlugin } from "module";
...
plugins: [
ViteFaviconsPlugin('/path/to/logo.png') // svg works too!
]
```
The default configuration will automatically generate webapp manifest files along with
[44 different icon formats](https://github.com/josh-hemphill/vite-plugin-favicon/tree/master/test/fixtures/expected/default)
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](#advanced-usage) 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](https://vitejs.dev/guide/api-plugin.html#transformindexhtml) it will also inject the necessary html for you:
```html
```
## Advanced Usage
```javascript
plugins: [
ViteFaviconsPlugin({
/** Your source logo (Will default to ) */
logo?: "assets/logo.png",
/** Inject html links/metadata. */
inject?: true,
/** `Favicons` configuration options
* - [See `favicons` documentation](https://github.com/itgalaxy/favicons) */
favicons?: FaviconsConfig,
/** The root of the project from which you want to load metadata */
projectRoot?: process.cwd(),
/** prefix is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated */
prefix?: string,
/** Caching is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated */
cache?: boolean,
/** Public Path is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated */
publicPath?: string,
/** Output Path is delegated to Rollup/Vite (keeping for people migrating from Webpack)
* @deprecated */
outputPath?: string,
})
]
```
To fine tune what icons/metadata is generated, refer to
[favicons' documentation](https://github.com/haydenbleasel/favicons#usage).
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`, simply set
to `null` the properties you want to omit.
### Examples
#### Basic
```javascript
const ViteFaviconsPlugin = require('vite-plugin-favicon')
// or ESM
import { ViteFaviconsPlugin } from "module";
plugins: [
ViteFaviconsPlugin({
logo: './src/logo.png', // svg works too!
favicons: {
appName: 'my-app',
appDescription: 'My awesome App',
developerName: 'Me',
developerURL: null, // prevent retrieving from the nearest package.json
background: '#ddd',
theme_color: '#333',
icons: {
coast: false,
yandex: false
}
}
})
]
```
To fine tune what icons/metadata is generated, refer to
[favicons' documentation](https://github.com/haydenbleasel/favicons#usage).
#### 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.
## Changelog
Take a look at the [CHANGELOG.md](https://github.com/josh-hemphill/vite-plugin-favicon/tree/latest/CHANGELOG.md).
## Contribution
You're free to contribute to this project by submitting [issues](https://github.com/josh-hemphill/vite-plugin-favicon/issues) and/or [pull requests](https://github.com/josh-hemphill/vite-plugin-favicon/pulls).
Please keep in mind that every change and feature should be covered by
tests.
## License
This project is licensed under [MIT](https://github.com/josh-hemphill/vite-plugin-favicon/blob/latest/LICENSE).
[favicons]: https://github.com/haydenbleasel/favicons
## Contributors