Favicons Webpack Plugin

Leverages on favicons to automatically generate your favicons for you.

Changes from fork

• See excludeManifestInjection option below.

Installation

Install the plugin with npm:

1$ npm install --save-dev favicons-webpack-plugin-ex

Zero Config Usage

Add your base logo as logo.png file to you webpack context folder. (By default the context is the current working directory)

Add the plugin to your webpack config as follows:

1const FaviconsWebpackPlugin = require('favicons-webpack-plugin-ex')
2
3plugins: [
4  new FaviconsWebpackPlugin()
5]

Basic Usage

Add the plugin to your webpack config as follows:

1const FaviconsWebpackPlugin = require('favicons-webpack-plugin-ex')
2
3...
4
5plugins: [
6  new FaviconsWebpackPlugin('/path/to/logo.png') // svg works too!
7]

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, Webpack resolves the path to logo 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 Webpack's context, which defaults to process.cwd().

• If path/to/logo is neither explicitly relative nor absolute, Webpack attempts to resolve it according to resolve.modules, which defaults to modules: ["node_modules"].

HTML Injection

In combination with html-webpack-plugin it will also inject the necessary html for you:

Note: html-webpack-plugin must come before favicons-webpack-plugin in the plugins array.

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 rel="apple-touch-startup-image" media="(device-width: 320px) and (device-height: 480px) and (-webkit-device-pixel-ratio: 1)" href="/assets/apple-touch-startup-image-320x460.png">
13<link rel="apple-touch-startup-image" media="(device-width: 320px) and (device-height: 480px) and (-webkit-device-pixel-ratio: 2)" href="/assets/apple-touch-startup-image-640x920.png">
14<link rel="apple-touch-startup-image" media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)" href="/assets/apple-touch-startup-image-640x1096.png">
15<link rel="apple-touch-startup-image" media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)" href="/assets/apple-touch-startup-image-750x1294.png">
16<link rel="apple-touch-startup-image" media="(device-width: 414px) and (device-height: 736px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 3)" href="/assets/apple-touch-startup-image-1182x2208.png">
17<link rel="apple-touch-startup-image" media="(device-width: 414px) and (device-height: 736px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 3)" href="/assets/apple-touch-startup-image-1242x2148.png">
18<link rel="apple-touch-startup-image" media="(device-width: 768px) and (device-height: 1024px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 1)" href="/assets/apple-touch-startup-image-748x1024.png">
19<link rel="apple-touch-startup-image" media="(device-width: 768px) and (device-height: 1024px) and (orientation: landscape) and (-webkit-device-pixel-ratio: 2)" href="/assets/apple-touch-startup-image-1496x2048.png">
20<link rel="apple-touch-startup-image" media="(device-width: 768px) and (device-height: 1024px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 1)" href="/assets/apple-touch-startup-image-768x1004.png">
21<link rel="apple-touch-startup-image" media="(device-width: 768px) and (device-height: 1024px) and (orientation: portrait) and (-webkit-device-pixel-ratio: 2)" href="/assets/apple-touch-startup-image-1536x2008.png">
22<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16x16.png">
23<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32x32.png">
24<link rel="icon" type="image/png" sizes="228x228" href="/assets/coast-228x228.png">
25<link rel="manifest" href="/assets/manifest.json">
26<link rel="shortcut icon" href="/assets/favicon.ico">
27<link rel="yandex-tableau-widget" href="/assets/yandex-browser-manifest.json">
28<meta name="apple-mobile-web-app-capable" content="yes">
29<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
30<meta name="apple-mobile-web-app-title">
31<meta name="application-name">
32<meta name="mobile-web-app-capable" content="yes">
33<meta name="msapplication-TileColor" content="#fff">
34<meta name="msapplication-TileImage" content="/assets/mstile-144x144.png">
35<meta name="msapplication-config" content="/assets/browserconfig.xml">
36<meta name="theme-color" content="#fff">

https://github.com/jantimon/favicons-webpack-plugin/blob/master/test/fixtures/expected/html

Advanced Usage

1plugins: [
2  new FaviconsWebpackPlugin({
3    // Your source logo (required)
4    logo: '/path/to/logo.png',
5    // Enable caching and optionally specify the path to store cached data
6    // Note: disabling caching may increase build times considerably
7    cache: true,
8    // Override the publicPath option usually read from webpack configuration
9    publicPath: '/static',
10    // The directory to output the assets relative to the webpack output dir.
11    // Relative string paths are allowed here ie '../public/static'. If this
12    // option is not set, `prefix` is used.
13    outputPath: '/public/static',
14    // Prefix path for generated assets
15    prefix: 'assets/',
16    // Inject html links/metadata (requires html-webpack-plugin).
17    // This option accepts arguments of different types:
18    //  * boolean
19    //    `false`: disables injection
20    //    `true`: enables injection if that is not disabled in html-webpack-plugin
21    //  * string
22    //    `'force'`: enables injection even if that is disabled in html-webpack-plugin
23    //  * function
24    //    any predicate that takes an instance of html-webpack-plugin and returns either
25    //    `true` or `false` to control the injection of html metadata for the html files
26    //    generated by this instance.
27    inject: true,
28    // Exclude injecting html links to manifest.json (requires html-webpack-plugin)
29    excludeManifestInjection: false,
30
31    // Favicons configuration options (see below)
32    favicons: {
33      ...
34    }
35  })
36]

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. To disable automatically retrieving metadata from package.json, simply set to null the properties you want to omit.

Examples

Basic

1const FaviconsWebpackPlugin = require('favicons-webpack-plugin-ex')
2
3plugins: [
4  new FaviconsWebpackPlugin({
5    logo: '/path/to/logo.png', // svg works too!
6    mode: 'webapp', // optional can be 'webapp' or 'light' - 'webapp' by default
7    devMode: 'webapp', // optional can be 'webapp' or 'light' - 'light' by default 
8    favicons: {
9      appName: 'my-app',
10      appDescription: 'My awesome App',
11      developerName: 'Me',
12      developerURL: null, // prevent retrieving from the nearest package.json
13      background: '#ddd',
14      theme_color: '#333',
15      icons: {
16        coast: false,
17        yandex: false
18      }
19    }
20  })
21]

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

Handling Multiple HTML Files

1const FaviconsWebpackPlugin = require('favicons-webpack-plugin-ex')
2const HtmlWebpackPlugin = require('html-webpack-plugin')
3const { basename } = require('path')
4
5...
6
7plugins: [
8    new HtmlWebpackPlugin({
9        template: 'a.html.tmpl',
10        filename: 'a.html',
11    }),
12    new HtmlWebpackPlugin({
13        template: 'b.html.tmpl',
14        filename: 'b.html',
15    }),
16    new FaviconsWebpackPlugin({
17        logo: 'logo.svg',
18        inject: htmlPlugin => 
19          basename(htmlPlugin.options.filename) === 'a.html',
20    }),
21],

Compilation Modes

Modes allow you to choose a very fast simplified favicon compilation or a production ready favicon compilation

By default this mode is controlled by webpack
If the webpack mode is set to development the favicons mode will use light. If the webpack mode is set to production the favicons mode will use webapp.

This behaviour can be adjusted by setting the favicon mode and devMode options.

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 new feature should be covered by tests.

License

This project is licensed under MIT.