Skip to main content
.com
Skip to main content
Algolia
Official Gatsby PluginOfficial Plugin
View plugin on GitHub
See starters using this

gatsby-plugin-manifest

Adds support for shipping a manifest.webmanifest with your site. The web application manifest is a JSON file that lets users (on Chrome, Edge, Firefox, Safari Mobile, and Opera — support in Safari Desktop is under development) save your web application to their smartphone home screen so it behaves similar to native apps.

This article from the Chrome DevRel team is a good intro to the web app manifest—https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/

For more information see the w3 spec https://www.w3.org/TR/appmanifest/ or Mozilla Docs https://developer.mozilla.org/en-US/docs/Web/Manifest.

If you’re using this plugin together with gatsby-plugin-offline (recommended), this plugin should be listed before the offline plugin so that it can cache the created manifest.webmanifest.

If you use the “automatic mode” or “hybrid mode” (described below), this plugin will also add a favicon link.

Install

npm install --save gatsby-plugin-manifest

How to use

This plugin configures Gatsby to create a manifest.webmanifest file on every site build.

Generating icons

It can be tedious creating the multitude of icon sizes required by different devices and browsers. This plugin includes code to auto-generate smaller icons from a larger src image (which can also be an SVG).

There are three modes in which icon generation can function: automatic, hybrid, and manual. These three modes are explained below. Icon generation functions differently depending on which of the three you choose.

Automatic mode

In the automatic mode, you are responsible for defining the entire web app manifest except for the icons portion. You only provide a high resolution source icon. The icons themselves and the needed config will be generated at build time. See the example gatsby-config.js below:

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        // Enables "Add to Homescreen" prompt and disables browser UI (including back button)
        // see https://developers.google.com/web/fundamentals/web-app-manifest/#display
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        include_favicon: true, // Include favicon
      },
    },
  ],
}

When in automatic mode the following json array is injected into the manifest configuration you provide and the icons are generated from it. The source icon you provide should be at least as big as the largest icon being generated.

[
  {
    "src": "icons/icon-48x48.png",
    "sizes": "48x48",
    "type": "image/png"
  },
  {
    "src": "icons/icon-72x72.png",
    "sizes": "72x72",
    "type": "image/png"
  },
  {
    "src": "icons/icon-96x96.png",
    "sizes": "96x96",
    "type": "image/png"
  },
  {
    "src": "icons/icon-144x144.png",
    "sizes": "144x144",
    "type": "image/png"
  },
  {
    "src": "icons/icon-192x192.png",
    "sizes": "192x192",
    "type": "image/png"
  },
  {
    "src": "icons/icon-256x256.png",
    "sizes": "256x256",
    "type": "image/png"
  },
  {
    "src": "icons/icon-384x384.png",
    "sizes": "384x384",
    "type": "image/png"
  },
  {
    "src": "icons/icon-512x512.png",
    "sizes": "512x512",
    "type": "image/png"
  }
]

The automatic mode is the easiest option for most people.

Hybrid mode

However, if you want to include more or fewer sizes, then the hybrid option is for you. Like automatic mode, you should include a high resolution icon to generate smaller icons from. But unlike automatic mode, you provide the icons array config and icons are generated based on the sizes defined in your config. Here’s an example gatsby-config.js:

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        // Enables "Add to Homescreen" prompt and disables browser UI (including back button)
        // see https://developers.google.com/web/fundamentals/web-app-manifest/#display
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        icons: [
          {
            src: `/favicons/android-chrome-192x192.png`,
            sizes: `192x192`,
            type: `image/png`,
          },
          {
            src: `/favicons/android-chrome-512x512.png`,
            sizes: `512x512`,
            type: `image/png`,
          },
        ],
      },
    },
  ],
}

The hybrid option allows the most flexibility while still not requiring you to create most icons sizes manually.

Manual mode

In the manual mode, you are responsible for defining the entire web app manifest and providing the defined icons in the static directory. Only icons you provide will be available. There is no automatic resizing done for you. See the example gatsby-config.js below:

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        // Enables "Add to Homescreen" prompt and disables browser UI (including back button)
        // see https://developers.google.com/web/fundamentals/web-app-manifest/#display
        display: `standalone`,
        icons: [
          {
            // Everything in /static will be copied to an equivalent
            // directory in /public during development and build, so
            // assuming your favicons are in /favicons,
            // you can reference them here
            src: `/favicons/android-chrome-192x192.png`,
            sizes: `192x192`,
            type: `image/png`,
          },
          {
            src: `/favicons/android-chrome-512x512.png`,
            sizes: `512x512`,
            type: `image/png`,
          },
        ],
      },
    },
  ],
}

Legacy option

iOS 11.3 added support for service workers but not the complete webmanifest spec. Therefore iOS won’t recognize the icons defined in the webmanifest and the creation of apple-touch-icon links in <head> is needed. This plugin creates them by default. If you don’t want those icons to be generated you can set the legacy option to false in plugin configuration:

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        legacy: false, // this will not add apple-touch-icon links to <head>
      },
    },
  ],
}

Removing theme-color meta tag

By default gatsby-plugin-manifest inserts <meta content={theme_color} name="theme-color" /> tag to html output. This can be problematic if you want to programatically control that tag - for example when implementing light/dark themes in your project. You can set theme_color_in_head plugin option to false to opt-out of this behavior.

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        theme_color_in_head: false, // This will avoid adding theme-color meta tag.
      },
    },
  ],
}

Excludes <link rel="shortcut icon" href="/favicon.png" /> link tag to html output. You can set include_favicon plugin option to false to opt-out of this behaviour.

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        include_favicon: false, // This will exclude favicon link tag
      },
    },
  ],
}

Disabling or changing ”Cache Busting” Mode

Cache Busting allows your updated icon to be quickly/easily visible to your sites visitors. HTTP caches could otherwise keep an old Icon around for days and weeks. Cache busting is only done in ‘automatic’ and ‘hybrid’ modes.

Cache busting works by calculating a unique “digest” or “hash” of the provided icon and modifying links and file names of generated images with that unique digest. If you ever update your icon, the digest will change and caches will be busted.

Options:

  • `query` - This is the default mode. File names are unmodified but a URL query is appended to all links. e.g. icons/icon-48x48.png?digest=abc123

  • `name` - Changes the cache busting mode to be done by file name. File names and links are modified with the icon digest. e.g. icons/icon-48x48-abc123.png (only needed if your CDN does not support URL query based cache busting)

  • `none` - Disables cache busting. File names and links remain unmodified.

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        cache_busting_mode: `none`, // `none`, `name` or `query`
      },
    },
  ],
}

Enable CORS using crossorigin attribute

Add a crossorigin attribute to the manifest <link rel="manifest" crossorigin="use-credentials" href="/manifest.webmanifest" /> link tag.

You can set crossOrigin plugin option to 'use-credentials' to enable sharing resources via cookies. Any invalid keyword or empty string will fallback to 'anonymous'.

You can find more information about crossorigin on MDN.

https://developer.mozilla.org/en-US/docs/Web/HTML/CORSsettingsattributes

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `GatsbyJS`,
        short_name: `GatsbyJS`,
        start_url: `/`,
        background_color: `#f7f0eb`,
        theme_color: `#a2466c`,
        display: `standalone`,
        icon: `src/images/icon.png`, // This path is relative to the root of the site.
        crossOrigin: `use-credentials`,
      },
    },
  ],
}

Edit this page on GitHub
Docs
Tutorial
Plugins
Blog
Showcase