Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/josh-hemphill/vite-plugin-favicon

Leverages on 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.
https://github.com/josh-hemphill/vite-plugin-favicon

favicons html plugin rollup vite

Last synced: about 1 month ago
JSON representation

Leverages on 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.

Awesome Lists containing this project

README

        

# Favicons Vite Plugin

[![version](https://img.shields.io/github/v/tag/josh-hemphill/vite-plugin-favicon?sort=semver&style=?style=plastic)](https://github.com/josh-hemphill/vite-plugin-favicon/releases)
[![NPM](https://img.shields.io/static/v1?label=&message=NPM&color=informational&style=?style=plastic)](https://npmjs.org/package/vite-plugin-favicon)
[![Codecov](https://img.shields.io/codecov/c/github/josh-hemphill/vite-plugin-favicon.svg?style=?style=plastic)](https://codecov.io/gh/josh-hemphill/vite-plugin-favicon)
[![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/vite-plugin-favicon?label=Deps&style=?style=plastic)](https://libraries.io/npm/vite-plugin-favicon)
[![Rate on Openbase](https://badges.openbase.io/js/rating/vite-plugin-favicon.svg)](https://openbase.io/js/vite-plugin-favicon?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge)
[![Test](https://github.com/josh-hemphill/vite-plugin-favicon/actions/workflows/test.yml/badge.svg)](https://github.com/josh-hemphill/vite-plugin-favicon/actions/workflows/test.yml)
[![Release](https://github.com/josh-hemphill/vite-plugin-favicon/actions/workflows/release.yml/badge.svg)](https://github.com/josh-hemphill/vite-plugin-favicon/actions/workflows/release.yml)

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 "vite-plugin-favicon";

...

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 "vite-plugin-favicon";

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