@mxjoly/pwa-webpack-plugin

PWA Webpack Plugin

Summary

• Installation
• Features
• Usage
• Options
• Configuration
• Metada
• License

Installation

npm install @mxjoly/pwa-webpack-plugin --save-dev

This package must be used with html-webpack-plugin and webpack-manifest-plugin :

npm install html-webpack-plugin webpack-manifest-plugin --save-dev

Features

This plugin:

• Generates all icons and splash screens for your application to be supported with all platforms (android, safari, apple, coast, windows)
• Creates the manifest.json
• Creates the browserconfig.xml
• Generates and injects the metadata to the html template file (with html-webpack-plugin)

Usage

1. Create a configuration file at the root of your project with the options for your manifest file:

app.json

{
  "lang": "en",
  "dir": "auto",
  "name": "Progressive Web App",
  "short_name": "PWA",
  "description": "This is a progressive web application",
  "scope": "/",
  "start_url": "/?utm_source=homescreen",
  "display": "standalone",
  "orientation": "any",
  "theme_color": "#323232",
  "background_color": "#ffffff"
}

1. Add the plugin to the webpack config file:

webpack.config.js

const fs = require('fs');
const HtmlPlugin = require('html-webpack-plugin');
const ManifestPlugin = require('webpack-manifest-plugin');
const PWAPlugin = require('@mxjoly/pwa-webpack-plugin');

const appDirectory = fs.realpathSync(process.cwd());
const faviconPath = path.resolve(appDirectory, 'src/favicon.svg');
const manifestOptions = require('./app.json');

module.exports = {
  plugins: [
    new HtmlPlugin({
      publicPath: '/',
    }),
    new PWAPlugin({
      publicPath: '/',
      emitMetadata: true,
      manifest: {
        options: manifestOptions,
      },
      icons: {
        favicon: faviconPath,
        outputPath: 'assets/icons',
        backgroundColor: '#ffffff',
        themeColor: '#ffffff',
        use: {
          favicons: true,
          android: true,
          apple: true,
          appleStartup: true,
          windows: true,
          safari: true,
          coast: true,
        },
      },
    }),
    new ManifestPlugin({
      fileName: 'assets-manifest.json',
      publicPath: '/',
    }),
  ],
};

Icons configuration

You can import the icons configuration used by the plugin.

const { getConfigurationFile } = require('@mxjoly/pwa-webpack-plugin');

Options

publicPath

The publicPath used for script and link tags. By default "/".

emitMetadata

Used to inject the metadata in your html template file. By default true.

manifest

filename

The filename of your manifest file. By default "manifest.json".

outputPath

The output path for your manifest file from the public path. By default "/".

options

An object with the options to use for your manifest file:

Key	Default	Description
name	null	Your application's name.
short_name	null	Your application's short_name.
description	null	Your application's description.
lang	en	Primary language for name and short_name
dir	auto	The base direction in which to display direction-capable members of the manifest.
background_color	#ffffff	Background colour for flattened icons.
theme_color	#ffffff	Theme color user for example in Android's task switcher.
display	standalone	Display mode: fullscreen, standalone, minimal-ui or browser.
scope	/	set of URLs that the browser considers within your app
start_url	/?utm_source=homescreen	Start URL when launching the application from a device.
orientation	any	The orientation to use

You can add more properties. For more informations see https://developer.mozilla.org/en-US/docs/Web/Manifest.

icons

The icons options allows you to control which icons will be generated during the webpack compilation.

favicon

The resolve path to your favicon. This favicon must have an svg format to generate the other icons.

outputPath

The ouput path of the icons from the public path. By default "/assets/icons".

backgroundColor

The background color used for the splash icons. By default "#ffffff".

themeColor

The theme color for your common icons. By default "#ffffff".

use

An object with the icon types to generate:

Key	Default	Description
favicons	true	The default favicons with sizes 16x16, 32x32, 48x48 and 96x96.
android	true	The chrome icons specified in the manifest.json.
apple	true	The apple touch icons.
appleStartup	true	The apple icons used for the splash screen.
windows	true	The msapplication tiles for browserconfig.xml.
safari	true	The mask icon used with safari.
coast	true	The specific icons used in coast.

Configuration

You can configure the icons that will be generated by creating icons.json at the root of your project with the schema defined in lib/schema.json. The following table figure out the different properties of the image configuration:

Properties	Type	Description
width	number	The width of the icon.
height	number	The height of the icon.
dwidth	number	The screen width of the device.
dheight	number	The screen height of the device.
ratio	number	The pixel ratio of the screen.
rel	string	The value of the rel attribute for the html tag.
type	mimetype	The mime type for the output image.
transparent	boolean	Set the background transparent.
mask	boolean	To get a mask icon.
shadow	boolean	Use shadow for the icon.
emitTag	boolean	Emit the tag to the html header.

Metadata

The generated metadata are the following tags:

<link rel="manifest" href="/manifest.json" />
<meta name="msapplication-config" href="/browserconfig.xml" />
<link
  rel="icon"
  type="image/png"
  href="/assets/icons/favicon-16x16.png"
  sizes="16x16"
/>
<link
  rel="icon"
  type="image/png"
  href="/assets/icons/favicon-32x32.png"
  sizes="32x32"
/>
<link
  rel="icon"
  type="image/png"
  href="/assets/icons/favicon-48x48.png"
  sizes="48x48"
/>
<link
  rel="icon"
  type="image/png"
  href="/assets/icons/favicon-96x96.png"
  sizes="96x96"
/>
<link
  rel="apple-touch-icon"
  type="image/png"
  href="/assets/icons/apple-touch-icon.png"
  sizes="180x180"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphone5-splash.png"
  media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphone6-splash.png"
  media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphoneplus-splash.png"
  media="(device-width: 621px) and (device-height: 1104px) and (-webkit-device-pixel-ratio: 3)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphonex-splash.png"
  media="(device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphonexr-splash.png"
  media="(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/iphonexsmax-splash.png"
  media="(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 3)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/ipad-splash.png"
  media="(device-width: 768px) and (device-height: 1024px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/ipadpro1-splash.png"
  media="(device-width: 834px) and (device-height: 1112px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/ipadpro2-splash.png"
  media="(device-width: 834px) and (device-height: 1194px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="apple-touch-startup-image"
  type="image/png"
  href="/assets/icons/ipadpro3-splash.png"
  media="(device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2)"
/>
<link
  rel="mask-icon"
  type="image/svg+xml"
  href="/assets/icons/safari-pinned-tab.svg"
/>
<link
  rel="icon"
  type="image/png"
  href="/assets/icons/coast-228x228.png"
  sizes="228x228"
/>

License

MIT.