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"
}

2. 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.