feat(web): generate manifest.json images (#3797)

- closes #1356

Author: abraham

docs/tutorials/03-styling.md

@@ -34,6 +34,10 @@ Every component reads the theme through CSS variables that start with `--hb-`, s
 
 The header shows `packages/web/public/images/logo.svg`, made for light backgrounds. Add `logo-dark.svg` next to it for the dark scheme. Without it, the header shows `shortName` from `site.json` as text in the dark scheme.
 
+## App icon
+
+The icon of the installed app, and of the site on phone home screens, is `packages/web/public/images/icon.png`. The build resizes it to every size the web app manifest and browsers need, from 16 to 512 pixels, including the favicon. Replace it with a square PNG of at least 512×512 pixels, or point `icon` in `site.json` at a square SVG in `packages/web/public`. An icon that isn't square sits centered on a transparent square.
+
 ## Colors
 
 Override any theme color in `theme.colors`, as a hex color. Dark colors are in `theme.darkColors`:

packages/web/build/build.smoke.test.ts

@@ -115,6 +115,19 @@ describe('a production build of a minimal site', () => {
     });
   });
 
+  it("makes every icon in the manifest and the page's favicons from the site's icon", () => {
+    const { icons } = JSON.parse(build.read('manifest.json')) as { icons: { src: string }[] };
+    const favicons = [
+      ...build.read('index.html').matchAll(/<link href="([^"]+)" rel="icon" sizes="(\d+)x\2"/g),
+    ].map(([, href]) => href ?? '');
+
+    expect(icons.length).toBeGreaterThan(0);
+    expect(favicons).toEqual(['images/manifest/icon-16.png', 'images/manifest/icon-32.png']);
+    for (const src of [...icons.map(({ src }) => src), ...favicons]) {
+      expect(build.read(src).slice(1, 4), src).toBe('PNG');
+    }
+  });
+
   it('lists the home page in the sitemap, and links to it from robots.txt', () => {
     const locs = (file: string) =>
       [...build.read(file).matchAll(/<loc>([^<]*)<\/loc>/g)].map(([, loc]) => loc);

packages/web/build/icon-module.d.ts

@@ -0,0 +1,4 @@
+// Types for `virtual:hoverboard/icon`, which vite-plugin-site.ts serves. tsconfig.json maps it here.
+
+/** The absolute path of `icon` from site.json. */
+export declare const iconFile: string;

packages/web/build/icons.test.ts

@@ -0,0 +1,66 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { iconErrors, pngSize } from './icons';
+
+const png = (width: number, height = width) =>
+  sharp({ create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } })
+    .png()
+    .toBuffer();
+
+describe('pngSize', () => {
+  it("reads a PNG's width and height", async () => {
+    expect(pngSize(await png(640, 480))).toEqual({ width: 640, height: 480 });
+  });
+
+  it('is undefined for other files', () => {
+    expect(pngSize(Buffer.from('<svg></svg>'))).toBeUndefined();
+    expect(pngSize(Buffer.from('\u0089PNG'))).toBeUndefined();
+  });
+});
+
+describe('iconErrors', () => {
+  let publicDir: string;
+
+  beforeEach(() => {
+    publicDir = mkdtempSync(join(tmpdir(), 'hoverboard-icon-'));
+  });
+
+  afterEach(() => rmSync(publicDir, { recursive: true, force: true }));
+
+  it('accepts a PNG of at least 512×512 pixels, and any SVG', async () => {
+    writeFileSync(join(publicDir, 'icon.png'), await png(1024));
+    writeFileSync(join(publicDir, 'icon.svg'), '<svg viewBox="0 0 24 24"></svg>');
+
+    expect(iconErrors('icon.png', publicDir)).toEqual([]);
+    expect(iconErrors('icon.svg', publicDir)).toEqual([]);
+  });
+
+  it('rejects an icon that is not in packages/web/public', () => {
+    expect(iconErrors('images/missing.png', publicDir)).toEqual([
+      'site.json/icon: "images/missing.png" is not in packages/web/public',
+    ]);
+  });
+
+  it('rejects a PNG that is too small for the largest icon', async () => {
+    writeFileSync(join(publicDir, 'icon.png'), await png(512, 256));
+
+    expect(iconErrors('icon.png', publicDir)).toEqual([
+      'site.json/icon: "icon.png" is 512×256 pixels, and needs to be at least 512×512',
+    ]);
+  });
+
+  it('rejects a .png file that is not a PNG', () => {
+    writeFileSync(join(publicDir, 'icon.png'), 'not a png');
+
+    expect(iconErrors('icon.png', publicDir)).toEqual([
+      'site.json/icon: "icon.png" is not a PNG file',
+    ]);
+  });
+
+  it("accepts the repository's icon", () => {
+    expect(iconErrors('images/icon.png', join(import.meta.dirname, '../public'))).toEqual([]);
+  });
+});

packages/web/build/icons.ts

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import { extname, join } from 'node:path';
+import { ICON_SIZES } from '../src/data/icons';
+
+const MIN_SIZE = Math.max(...ICON_SIZES);
+
+/** A PNG's size, from its header. */
+export const pngSize = (data: Buffer): { width: number; height: number } | undefined =>
+  data.toString('latin1', 1, 4) === 'PNG' && data.length >= 24
+    ? { width: data.readUInt32BE(16), height: data.readUInt32BE(20) }
+    : undefined;
+
+/** The site icon must be in packages/web/public, and a PNG big enough for the largest icon. */
+export const iconErrors = (icon: string, publicDir: string): string[] => {
+  const file = join(publicDir, icon);
+  if (!fs.existsSync(file)) return [`site.json/icon: "${icon}" is not in packages/web/public`];
+  if (extname(icon).toLowerCase() !== '.png') return [];
+  const size = pngSize(fs.readFileSync(file));
+  if (!size) return [`site.json/icon: "${icon}" is not a PNG file`];
+  return size.width < MIN_SIZE || size.height < MIN_SIZE
+    ? [
+        `site.json/icon: "${icon}" is ${size.width}×${size.height} pixels, and needs to be at least ${MIN_SIZE}×${MIN_SIZE}`,
+      ]
+    : [];
+};

packages/web/build/resolve-config.test.ts

@@ -241,6 +241,18 @@ describe('config validation', () => {
     ]);
   });
 
+  it('rejects an icon that is not a PNG or SVG in packages/web/public', () => {
+    expect(errorsFor({ site: { icon: 'images/missing.png' } })).toEqual([
+      'site.json/icon: "images/missing.png" is not in packages/web/public',
+    ]);
+    expect(errorsFor({ site: { icon: 'https://example.com/icon.png' } })).toEqual([
+      expect.stringMatching(/^site\.json\/icon: must match pattern/),
+    ]);
+    expect(errorsFor({ site: { icon: 'images/social-share.jpg' } })).toEqual([
+      expect.stringMatching(/^site\.json\/icon: must match pattern/),
+    ]);
+  });
+
   it('rejects a hero illustration that is not an SVG in packages/web/public', () => {
     expect(
       errorsFor({ site: { heroSettings: { home: { illustration: '/images/missing.svg' } } } }),

packages/web/build/resolve-config.ts

@@ -9,6 +9,7 @@ import {
 } from '../src/config/features';
 import { deepMerge, isPlainObject } from '../src/config/merge';
 import { fontProblems } from './fonts';
+import { iconErrors } from './icons';
 import { sanitizeSvg } from './svg';
 import {
   type ResolvedTheme,
@@ -205,6 +206,7 @@ const crossFileErrors = (site: Site, resources: Resources, paths: ConfigPaths):
       errors.push(`${path}: "${image}" is not in packages/web/public`);
     }
   }
+  errors.push(...iconErrors(site.icon, paths.public));
   // The page inlines it, so it can be drawn in the theme's colors.
   const illustration = site.heroSettings?.home?.illustration;
   if (illustration && (isUrl(illustration) || !fs.existsSync(join(paths.public, illustration)))) {

packages/web/build/vite-plugin-site.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import n from 'nunjucks';
 import type { Plugin, PluginOption } from 'vite';
 import copy from 'rollup-plugin-copy';
@@ -29,6 +29,9 @@ const RESOLVED_FONTS_MODULE = `\0${FONTS_MODULE}`;
 // The fonts, colors and logo of the share images. Only server code imports it.
 export const SOCIAL_IMAGES_MODULE = 'virtual:hoverboard/social-images';
 const RESOLVED_SOCIAL_IMAGES_MODULE = `\0${SOCIAL_IMAGES_MODULE}`;
+// The app icon's file, which the icon pages resize. Only server code imports it.
+export const ICON_MODULE = 'virtual:hoverboard/icon';
+const RESOLVED_ICON_MODULE = `\0${ICON_MODULE}`;
 // One module per locale, `virtual:hoverboard/content/<locale>`, so each is its own chunk.
 export const CONTENT_MODULE = 'virtual:hoverboard/content/';
 const RESOLVED_CONTENT_MODULE = `\0${CONTENT_MODULE}`;
@@ -68,6 +71,7 @@ export const siteModule = (
     if (id === LAYOUT_MODULE) return RESOLVED_LAYOUT_MODULE;
     if (id === FONTS_MODULE) return RESOLVED_FONTS_MODULE;
     if (id === SOCIAL_IMAGES_MODULE) return RESOLVED_SOCIAL_IMAGES_MODULE;
+    if (id === ICON_MODULE) return RESOLVED_ICON_MODULE;
     const locale = id.startsWith(CONTENT_MODULE) ? id.slice(CONTENT_MODULE.length) : undefined;
     return locale && Object.hasOwn(config.contentTranslations, locale)
       ? `${RESOLVED_CONTENT_MODULE}${locale}`
@@ -111,6 +115,9 @@ export const siteModule = (
         .map(([name, value]) => `export const ${name} = ${JSON.stringify(value)};\n`)
         .join('');
     }
+    if (id === RESOLVED_ICON_MODULE) {
+      return `export const iconFile = ${JSON.stringify(resolve(publicDir, site.icon))};\n`;
+    }
     if (id.startsWith(RESOLVED_CONTENT_MODULE)) {
       const locale = id.slice(RESOLVED_CONTENT_MODULE.length);
       return `export default ${JSON.stringify(contentTranslations[locale])};\n`;

packages/web/defaults/site.json

@@ -1,6 +1,7 @@
 {
   "basepath": "/",
   "image": "images/social-share.jpg",
+  "icon": "images/icon.png",
   "schedule": {
     "published": true
   },