@pwa-manifest/core

Core package for PWA manifest generation. Can be integrated into a build pipeline. Handles user input directly, no need to clean it.

Documentation

This package exports a single class PWAManifestGenerator. It uses ES Modules for exports.

ES Modules/TypeScript import:

1import PWAManifestGenerator from '@pwa-manifest/core';

CommonJS/Node.js import:

1const PWAManifestGenerator = require('@pwa-manifest/core').default;

To construct a PWAManifestGenerator object, instantiate with the new keyword and the options for generation. (The list of options are detailed below.)

1const generator = new PWAManifestGenerator({
2  name: 'My Awesome PWA',
3  shortName: 'My PWA',
4  startURL: './offline',
5  theme: '#add8e6',
6  iconGenerationOptions: {
7    baseIcon: './public/my-awesome-icon.svg',
8    sizes: [192, 384, 512],
9    genFavicons: true
10  }
11});

You can also optionally pass in a resolveDir (from which relative paths are resolved, defaults to the current working directory), a baseURL (from which all generated filepaths will begin, defaults to '/'), and default options (which will take the place of missing parameters in the actual options object. This is mainly for plugin developers.)

1const opts = JSON.parse(fs.readFileSync('myConfig.json').toString());
2const generator = new PWAManifestGenerator(opts, {
3  baseURL: '.',
4  resolveDir: __dirname
5}, {
6  name: 'Default App Name',
7  description: 'A default description!',
8  theme: 'yellow'
9});

After you create the generator, you can generate the manifest, HTML to be injected, Microsoft Browser Config, and icons easily with the asynchronous generate() method.

To convert the HTML insertion array into a string, use the htmlInsertToString method:

1const {
2  default: PWAManifestGenerator,
3  htmlInsertToString
4} = require('@pwa-manifest/core');
5/* Use the following for ES Modules:
6import PWAManifestGenerator, { htmlInsertToString } from '@pwa-manifest/core';
7*/
8
9async function generateFromOpts(opts) {
10  const generator = new PWAManifestGenerator(opts);
11  const generation = await generator.generate();
12  fs.writeFileSync('manifest.webmanifest', JSON.stringify(generation.manifest));
13  fs.writeFileSync('browserconfig.xml', generation.browserConfig);
14  for (const filename in generation.generatedFiles) {
15    fs.writeFileSync(filename, generation.generatedFiles[filename]);
16  }
17  let html = fs.readFileSync('index.html').toString();
18  const htmlHeadIndex = html.indexOf('</head>');
19  html = html.slice(0, htmlHeadIndex)
20         + generation.html.map(htmlInsertToString).join('')
21         + html.slice(htmlHeadIndex);
22  fs.writeFileSync('index.html', html);
23}

If you need to generate one type of icon at a time, just call the respective method manually, and it will add the result into the generator object:

1await generator.genAppleTouchIcon();
2// generator.generatedFiles now contains the Apple Touch Icon

Options

Almost anything that usually goes in a manifest.webmanifest file can go into the options. All parameter names have aliases in the original form from the spec (like start_url), in camel case (recommended, like startUrl), in kebab case (like start-url), and in other reasonable forms (like startURL). If you see any inconsistencies in the documentation, it's probably fine; you can use multiple names for the same value.

All parameters that exist in the MDN documentation for the Web App Manifest are aliased, type-checked, and inserted into the manifest whenever provided in the options. There are a few reasonable defaults, like '.' for start_url. Watch out for three changes, though: the removal of the icons option to allow icon generation and the modification of the screenshots and shortcuts options' behavior (detailed below).

If you need to have a parameter not included in that list, put an array of parameter names to keep in the final manifest under the include key. If you use an unknown parameter name and don't put it in include, the generation will throw an error.

Changes from standard manifest

The theme_color (aka theme) will default to white and will change the default behavior of some parts of the icon generation, such as the background color of the Microsoft Tile.

The screenshots, unlike in a normal web app manifest, should be an array of screenshot image filepaths or absolute URLs. Do not use relative URLs or they will be confused for filepaths. Each image should be a PNG, JPEG, or WebP file.

Each shortcut in the shortcuts should not include an icons field but rather a single icon, which will automatically be resized according to the icon generation options. The other fields like name, short_name have aliases.

Instead of manually setting an icons parameter containing a set of icons, you should use genIconOpts (aka iconGenerationOptions, iconGenOpts, ...you get the gist). genIconOpts will contain the options for icon generation. The parameters for genIconOpts are as follows:

baseIcon

The path to the icon to generate all other icons from. Path is relative to the resolveDir.

• For best results, use a high-resolution (at least 512x512) PNG or an SVG.

sizes

An array of pixel values for the sizes to generate. Defaults to [96, 152, 192, 384, 512].

• All PWAs need at least 192px and 512px icons, so those will be added in regardless of whether they are provided in the sizes parameter.

shortcutSizes

An array of pixel values for the sizes of the shortcut icons. Defaults to [96, 192].

• All PWAs need at least 96x shortcut icons, so those will be added in regardless of whether they are provided in the shortcutSizes parameter.

formats

An object whose keys are the desired output formats (in lowercase) and whose values are the configurations to use with the sharp package when generating icons of that type. By default, generates WebP and PNG images with somewhat high compression.

• If you prefer the user getting one format over another, put that format first in the object.
• All PWAs need at least PNG, so that's inserted first if you provide your own config. If you don't want it first, put your own png key-value pair in your config.

appleTouchIconBG

The background color for the Apple Touch Icon (to fill transparent regions). Defaults to the theme color.

• Useful because by default, Apple uses black for transparent regions, which doesn't look good with most icons.
• Recommended to use atib alias for brevity.

appleTouchIconPadding

The number of pixels to pad the Apple Touch Icon with on all sides. Defaults to 12.

• Used to account for Apple's courner-rounding.
• Recommended to use atip alias for brevity.

genFavicons

Whether or not to generate 16x16 and 32x32 favicons and insert links in the HTML. Defaults to false.

genSafariPinnedTab

Whether or not to generate a Safari Pinned Tab SVG icon using an autotracer. Defaults to false

• Has a significant impact on performance (not managed by sharp but by native JavaScript).
• Recommended to use genPinnedTab or gspt for brevity.

safariPinnedTabColor

The color for the Safari Pinned Tab icon. Defaults to the theme color (or 'black' if no theme was manually specified).

• Recommended to use pinnedTabColor or sptc for brevity.

msTileColor

The background color for Microsoft Tiles. Defaults to the theme color.

resizeMethod

The method to use for resizing non-square images. Can be one of 'cover' (default), 'contain', or 'fill'.

purpose

An array of possible purposes for the icons. Each element should be one of 'badge', 'maskable', or 'any'

disabled

Disables the manifest creation with no warning.

• Used to speed up builds when icon generation isn't needed (i.e. when developing with HMR)

production / development

The parameters to use when NODE_ENV is a certain value. Merged with the outer parameters.

• Useful for disabling/generating less icons in development
• Case-insensitive - use lowercase in options
• Can be anything. production and development are common, but you could hypothetically set your NODE_ENV to asdf and have an asdf key with custom manifest generation options

Advanced: Events

The generator has a rich event system. It extends EventEmitter, so you can use .on(eventName) to listen for them.

There are three types of event: start, gen, and end. Each of these events can apply to one of defaultIcons, appleTouchIcon, favicon, or msTile. Therefore, we have events for defaultIconsStart, msTileEnd, faviconGen, etc.

start events are called with a pretty string message about the status of the build you can log.

gen events are called with an object containing key filename, which maps to a promise resolving to the filename, and key content, which maps to a promise resolving to the raw image data. You can change the fields of these objects with your own promises in your event handlers to modify the output filename or content. Note that gen events can be called multiple times per build because they are called with each and every icon from the default icons and both generated favicons.

end events are not called with any extra information. They just notify when one task finishes.

There are three extra events that don't follow the above rules. The 'start' event (where the event is the literal string 'start' with no icon type) signifies the start of the generation as a whole and has no parameters. The 'end' event signifies the end of the generaiton as a whole and has no parameters. The '*' event is a wildcard that can be used to listen for every event, and handlers are called with first the event name, then the original parameters from the event.

All these events can be confusing, so here's a quick example:

1generator.on('*', (eventName, ...eventParameters) => {
2  if (eventName === 'start')
3    console.log('Build started!')
4  else if (eventName.endsWith('Start'))
5    console.log(eventParameters[0]); // Nice message
6  else if (eventName === 'end')
7    console.log('Build finished!');
8});
9generator.on('faviconGen', ev => {
10  /**
11   * If you want your changes to apply, do NOT make the handler itself async!
12   * Modify the event object synchronously, you can do asynchronous handling in
13   * the promise itself.
14   */
15  ev.filename = ev.filename.then(originalFilename => {
16    console.log('Modifying the name of', originalFilename);
17    return 'modified-name-' + originalFilename;
18  });
19  /**
20   * You'll want to do any postprocessing with your own image library here.
21   * This example assumes you have a `tintRed` function that, when given a
22   * Buffer containing image data, will return a buffer containing that image
23   * data tinted red.
24   */
25  ev.content = ev.content.then(buf => tintRed(buf))
26});

License

MIT