gatsby-plugin-realfavicongenerator

Generate webmanifest, favicon and device-specific icons for your PWA using realfavicongenerator.net.

Installation

yarn add gatsby-plugin-realfavicongenerator
# or
npm install --save gatsby-plugin-realfavicongenerator

then, add it to the plugins section in you gastby-config.js:

module.exports = {
    plugins: [
        resolve: `gatsby-plugin-realfavicongenerator`,
        options: {
            // see below
        },
    ],
};

Options

key required default value description
apiKey ✔️ - API-Key for the realfavicongenerator.net API.
masterPicture ✔️ - path to your master picture from which the icons should be generated. Should be at least 250x250.
appName ✔️ - Name of you PWA/Website
startUrl / Starturl of your PWA
themeColor ✔️ - The theme color of your PWA
display standalone Either standalone or browser. Controlls how your PWA behaves when added to the home screen
forceOrientation - Can be portrait or landscape. If set, forces the orientation of your PWA
defaultBackgroundColor - Default background color for the generated icons
defaultMargin - Default margin to add around the masterPicture when generating the icons
compression 3 Compression factor for the generated icons. Can be a number from 1 to 5
scalingAlgorithm Lanczos The scaling algorithm used to scale the master pciture. Possible options: 'Mitchell' | 'NearestNeighbor'| 'Cubic'| 'Bilinear'| 'Lanczos'| 'Spline'
ios {enabled: true, onlyDefaultIcons: true, legacyIcons: false, precomposedIcons: true} Options for the iOS icons. See below
windows {enabled: true} Options for the Windows icons. See below
android {enabled: true, legacyIcons: false, lowResIcons: false} Options for the Android/Chrome icons. See below
safariPinnedTab {enabled: true, silhouette: true, threshold: 60} Options for the Safari pinned tab icon. See below
openGraph {enabled: false} Options for the open graph images. See below
faviconRequestOverride - Option to override specific options from the favicon_generation sent to the realfavicongenerator.net API . Use with caution
transformGeneratedManifest - callback fucntion to transform/customize the content of the generated .webmanifest file. Signature: (manifest: {[key: string]: any}) => {[key: string]: any}. The returned object from this function is then converted back to JSON and replaces the content of the generated .webmanifest file

iOS

key required default value description
enabled ✔️ true Enable/Disable generation of iOS specific icons
masterPicture - Provide a specific image for the iOS icons. If not provided, master masterPicture from global options will be used
margin - Add margin around your masterPicture. Can be a number (pixels) or string (percentage, e.g. ‘5%‘)
backgroundColor - Background color for the icons
onlyDefaultIcons true Generate only default icons
legacyIcons false Generate also legacy icons
precomposedIcons true Generate precomposed icons
startupImage - Options for the image used as startup image/splash screen
startupImage.masterPicture ✔️ - Picture to use as startup image/splash screen
margin - Margin added around the startup image/splash screen
backgroundColor - Background color for the startup image/splash screen

Windows/IE/Edge

key required default value description
enabled ✔️ true Enable/Disable generation of the windows icons
masterPicture - Provide a specific image for the windows icons. If not provided, master masterPicture from global options will be used
backgroundColor - Background color for the images
silhouette - Convert icons to silhouette

Android/Chrome

key required default value description
enabled ✔️ true Enable/Disable generation of Android specific icons
masterPicture - Provide a specific image for the Android icons. If not provided, master masterPicture from global options will be used
margin - Add margin around your masterPicture. Can be a number (pixels) or string (percentage, e.g. ‘5%‘)
backgroundColor - Background color for the icons
legacyIcons false Generate also legacy icons
lowResIcons false Generate low resolution icons
existingManifest - Path to a template .webmanifest file, wich can be used to define additional properties

Safari Pinned Tab Icon

key required default value description
enabled ✔️ true Enable/Disable generation of Safari pinned tab icon
masterPicture - Provide a specific image for the Safari pinned tab icon. If not provided, master masterPicture from global options will be used
margin - Add margin around your masterPicture. Can be a number (pixels) or string (percentage, e.g. ‘5%‘)
backgroundColor - Background color for the icons
threshold 60 Threshold for converting to silhouette. A number between 0 and 100
silhouette true Convert icon to silhouette

OpenGraph

key required default value description
enabled ✔️ false Enable/Disable generation of OpenGraph images
masterPicture - Provide a specific image for the OpenGraph images. If not provided, master masterPicture from global options will be used
margin - Add margin around your masterPicture. Can be a number (pixels) or string (percentage, e.g. ‘5%‘)
backgroundColor - Background color for the images
ratio - Aspect ration of the generated images

Example usage

// gastby-config.js
module.exports = {
    plugins: [
        resolve: `gatsby-plugin-realfavicongenerator`,
        options: {
           apiKey: 'YOUR_API_KEY',
           masterPicture: 'src/assets/favicon.png',
           appName: 'My Awesome App',
           startUrl: '/',
           themeColor: '#000',
           display: 'standalone',
           defaultBackgroundColor: '#000',
           defaultMargin: '10%',
           compression: 3,
           scalingAlgorithm: 'Lanczos',
           ios: {
             enabled: true,
             onlyDefaultIcons: false,
             legacyIcons: true,
             precomposedIcons: true,
           },
           windows: {
             enabled: true,
             silhouette: true,
           },
           android: {
             enabled: true,
             legacyIcons: true,
             lowResIcons: true,
           },
           safariPinnedTab: {
             enabled: true,
             threshold: 60,
             silhouette: true,
           },
           openGraph: {
             enabled: true,
             ratio: 'square',
           },
           transformGeneratedManifest: (manifest) => {
             manifest.scope = '/';
             if (manifest.icons) {
               manifest.icons = manifest.icons.map((icon) => {
                 return {
                   ...icon,
                   purpose: 'maskable',
                 };
               });
             }
   
             return manifest;
           },
        },
    ],
};

About icon generation

Since the generation of the icons via realfavicongenerator.net can take a long time, icons are only generated on the first run, and the only updated if:

  1. The plugin options change
  2. The gatsby cache is cleared (e.g. via gastby clean)