Adapted from favgen to include more flexibility on the web manifest file

This is a simple CLI tool to generate an optimized set of favicons and a web manifest from a single input file and a web-config file. Icons are optimized in terms of both size and quantity (nowadays you don't need that many of them). They are produced according to this article which served as an inspiration for the tool.

Command Line Interface

The pwag command generates icons and manifest from an input file, and optionally injects PWA meta tags into HTML files:

npx pwag /path/to/input-image /path/to/web-config.json -o /path/to/output [options]

The script always generates icons and manifest first, then optionally injects PWA meta tags if the --html option is provided.

WebConfig type is found in src/types.ts

Generate Icons and Manifest

The script expect the image path as first arg and the web-config file as scond argument

the tool then generates optimized favicons and web manifest:

Options

• output directory by providing -o option with a path (static by default)
• icon prefix by providing --prefix option with a name (favicon by default)
• producing 16x16 .ico file by setting --include16 flag
• generating maskable icons by setting the --maskable flag (equivalent to "maskable": true in the web-config, which wins if both are set)

Input file can be in any of the following formats: JPEG, PNG, WebP, GIF, AVIF, TIFF or SVG (anything sharp library accepts).

By default, the following set of favicons is produced:

• favicon.svg if input file was SVG and favicon.png 32x32 otherwise
• favicon.ico 32x32
• favicon-192.png 192x192 (for Android devices)
• favicon-512.png 192x192 (for Android devices)
• apple-touch-icon.png 180x180 (original image is resized to 140x140 and 20px transparent padding is added on each side; rationale for this is given in the article)

Additionally, a sample manifest.webmanifest file is produced which shows how favicons for Android devices are supposed to be included.

Maskable Icons

Android (and other platforms) apply a mask to installed app icons. An icon that is not designed for it gets clipped, and a transparent icon lets the launcher background bleed through. Set maskable in the web-config and pwag generates the padded variants for you:

{
	"themeColor": "#000000",
	"maskable": true
}

This produces <prefix>-maskable-192.png and <prefix>-maskable-512.png, and adds them to the manifest with "purpose": "maskable". The logo is resized to 62% of the canvas and centered over a solid, fully opaque background, so it stays inside the maskable safe zone whatever shape the platform mask is.

The field also accepts an object to override the defaults:

{
	"maskable": {
		"background": "#4f46e5",
		"logoScale": 0.62,
		"sizes": [192, 512]
	}
}

• background: #rgb, #rrggbb or #rrggbbaa (the alpha is ignored, a maskable icon must be opaque). Defaults to #000000. This is intentionally independent of themeColor: the theme color is the browser-chrome color, and there's no reason a strong brand themeColor should bleed into the launcher icon.
• logoScale: portion of the canvas occupied by the logo, between 0 and 1. Defaults to 0.62.
• sizes: canvas sizes to generate. Defaults to [192, 512]. Both are emitted on purpose: Firefox Android expects a maskable icon at the 192 launcher size and falls back to a generated letter icon when only 512 is available.

The regular 192/512 icons are always emitted with an explicit "purpose": "any". The spec defaults a missing purpose to any, but some Firefox Android versions only adopt the manifest icon when it is spelled out. This is the only output change for configs that do not use maskable.

If you were running a hand-rolled post-process script after pwag to pad maskable icons and patch the manifest (such as a pwa-postprocess.mjs), you can drop it and set maskable: true instead.

The legacy maskableIcons field (hand-made files that must already exist in the output directory) keeps working and is appended after the generated ones, skipping duplicate src entries. maskable is the preferred path since it can never reference a missing file.

Screenshots

Chrome's "richer PWA install UI" (the richer install prompt on desktop and mobile) requires the web manifest to declare a screenshots array: at least one entry with form_factor: "wide" for desktop, and at least one with form_factor unset or set to a value other than "wide" (e.g. "narrow") for mobile. Without them Chrome logs:

Richer PWA Install UI won't be available on desktop. Please add at least one screenshot with the form_factor set to wide. Richer PWA Install UI won't be available on mobile. Please add at least one screenshot for which form_factor is not set or set to a value other than wide.

Set screenshots in the web-config and pwag copies the source images into the pwa output dir and emits the manifest screenshots[] entries for you, with sizes and type auto-detected from the image via sharp:

{
	"themeColor": "#000000",
	"screenshots": [
		{
			"src": "pwa-assets/screenshots/desktop.png",
			"out": "screenshot-desktop.png",
			"form_factor": "wide",
			"label": "Wherever dashboard on desktop"
		},
		{
			"src": "pwa-assets/screenshots/mobile.png",
			"out": "screenshot-mobile.png",
			"form_factor": "narrow",
			"label": "Wherever dashboard on mobile"
		}
	]
}

Each entry supports:

• src: path to the source image, relative to the current working directory (the same way the CLI input icon path is resolved), not relative to the web-config file. This means the screenshots can live outside the served static directory and are only copied into the pwa output dir at build time.
• out: output filename in the pwa dir. Defaults to basename(src). The manifest entry's src is this bare filename, so it resolves the same way the icon entries (favicon-192.png, ...) do regardless of the --subpath.
• form_factor: 'wide' or 'narrow'. Optional, but Chrome requires at least one wide and one non-wide for the richer install UI.
• label: optional human-readable description shown in the install UI.
• sizes: optional, auto-detected as "WxH" via sharp when omitted.
• type: optional, auto-detected from the output extension (.png->image/png, .jpg/.jpeg->image/jpeg, .webp->image/webp, .gif->image/gif, .avif->image/avif), falling back to image/<sharp-format>. Defaults to image/png when nothing else is available.

The source images are copied verbatim into the output dir (no re-encode), so they keep their exact bytes and can be authored in any format sharp can read (PNG, JPEG, WebP, GIF, AVIF). Missing sources fail the build loudly rather than silently emitting a manifest entry that points at a non-existent file.

A config without a screenshots field produces a manifest with no screenshots key, identical to a build that does not know about the feature, so existing configs are unchanged.

There is also a repeatable CLI flag that appends to the screenshots array (useful for one-off runs); the web-config's screenshots array, if present, is kept and appended after:

npx pwag icon.png web-config.json -o static --screenshot ./shots/desktop.png --screenshot ./shots/mobile.png

If you were running a hand-rolled post-process script after pwag to copy screenshots and patch the manifest (such as a pwa-postprocess.mjs using ImageMagick identify), you can drop it and set screenshots in the web-config instead. pwag uses sharp for dimensions, never ImageMagick.

Besides that, SVG output is optimized by sharp (using SVGO) and PNG output is encoded with sharp's default settings, which keeps smooth gradients in the source SVG from banding into concentric dithering rings.

Inject PWA Meta Tags

The tool can also inject meta tag in provided html

HTML Injection Options

• --html <path>: Required - HTML file path with PWAG-GENERATED markers to inject meta tags into
• --html-output <path>: Output HTML file path for template files (preserves original template file specified in --html)
• --base-url <url>: Base URL for relative paths
• --assets-prefix <prefix>: Assets prefix for different frameworks (default: ".")

HTML Template Requirements

Your HTML file must contain these markers:

<head>
	<!--PWAG-GENERATED-->
	<!--PWAG-GENERATED-->

	<!-- Other head content -->
</head>

The script will replace the content between these markers with the generated PWA tags, preserving the original indentation.

Examples

# Generate icons (existing functionality)
npx pwag icon.png web/src/web-config.json -o static

# Inject into HTML file (modifies original)
npx pwag icon.png web/src/web-config.json -o static --html web/build/index.html

# Inject into HTML with options
npx pwag icon.png web/src/web-config.json -o static --html web/build/index.html --assets-prefix "%sveltekit.assets%"

# Generate HTML output (preserves template)
npx pwag icon.png web/src/web-config.json -o static --html web/build/index.html --html-output web/build/index.html

This generates comprehensive meta tags including:

• Basic meta tags: title, description, theme color
• Open Graph tags: for social media sharing
• Twitter Card tags: for Twitter sharing
• Icon links: favicons, apple-touch-icon, manifest
• PWA meta tags: mobile-web-app-capable, application-name
• Apple specific tags: apple-mobile-web-app settings
• Conditional ENSName: only included if specified in config
• Preserved indentation: Both markers maintain original file indentation

Programmatic API

const { produceIconsAndManifest, injectPWAIntoHTML, injectPWAIntoHTMLWithOutput } = require('pwag');

// Generate icons and manifest
const inputFilePath = 'favicon.svg';
const outputDirPath = 'static';
const subpath = 'pwa';
const prefix = 'favicon'; // default value
const include16 = true; // default is false
produceIconsAndManifest(
	{
		outputDirPath: outputDirPath,
		subpath,
		iconFileName: prefix,
		inputFilePath,
		include16,
	},
	{},
);

// Inject PWA meta tags into HTML (modifies original)
injectPWAIntoHTML('web/build/index.html', 'web/src/web-config.json', {
	baseUrl: '/app',
	assetsPrefix: '%sveltekit.assets%',
});

// Inject PWA meta tags into HTML (preserves template)
injectPWAIntoHTMLWithOutput(
	'web/src/template.html',
	'web/src/web-config.json',
	'web/build/index.html',
	{
		baseUrl: '/app',
		assetsPrefix: '%sveltekit.assets%',
	},
);