A webpack plugin that generates your icons and metadata for your progressive web app.
npm install @mxjoly/pwa-webpack-plugin
- Installation
- Features
- Usage
- Options
- Configuration
- Metada
- License
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
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)
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
`javascript
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: '/',
}),
],
};
`
You can import the icons configuration used by the plugin.
`javascript`
const { getConfigurationFile } = require('@mxjoly/pwa-webpack-plugin');
The publicPath used for script and link tags. By default "/".
Used to inject the metadata in your html template file. By default true.
#### 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.
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. |
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. |
The generated metadata are the following tags:
`html``
type="image/png"
href="/assets/icons/favicon-16x16.png"
sizes="16x16"
/>
type="image/png"
href="/assets/icons/favicon-32x32.png"
sizes="32x32"
/>
type="image/png"
href="/assets/icons/favicon-48x48.png"
sizes="48x48"
/>
type="image/png"
href="/assets/icons/favicon-96x96.png"
sizes="96x96"
/>
type="image/png"
href="/assets/icons/apple-touch-icon.png"
sizes="180x180"
/>
type="image/png"
href="/assets/icons/iphone5-splash.png"
media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/iphone6-splash.png"
media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/iphoneplus-splash.png"
media="(device-width: 621px) and (device-height: 1104px) and (-webkit-device-pixel-ratio: 3)"
/>
type="image/png"
href="/assets/icons/iphonex-splash.png"
media="(device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3)"
/>
type="image/png"
href="/assets/icons/iphonexr-splash.png"
media="(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/iphonexsmax-splash.png"
media="(device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 3)"
/>
type="image/png"
href="/assets/icons/ipad-splash.png"
media="(device-width: 768px) and (device-height: 1024px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/ipadpro1-splash.png"
media="(device-width: 834px) and (device-height: 1112px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/ipadpro2-splash.png"
media="(device-width: 834px) and (device-height: 1194px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/png"
href="/assets/icons/ipadpro3-splash.png"
media="(device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2)"
/>
type="image/svg+xml"
href="/assets/icons/safari-pinned-tab.svg"
/>
type="image/png"
href="/assets/icons/coast-228x228.png"
sizes="228x228"
/>