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)