Installable app (PWA)

Turn the site into an app people install from their phone's home screen or as a desktop app. You give it a name, colors and one icon; Arc CMS builds the rest.

What it is

With the PWA on, the build adds a web app manifest, every icon size, and a service worker. People get:

• An install card that shows the right steps for their browser.
• Fast opening: the app's main code, styles and fonts are stored on the device; other code, images and fonts from the site and common font and script CDNs are stored the first time they load. A person's own files in Storage (users/...) are never stored, so nothing private stays on a shared device.
• Fresh content: pages always come from the network first. Without a connection, or after 4 seconds of waiting (navigationTimeoutSeconds), the stored copy opens instead. After an update, a stored page of the old version is not used: its code is gone, so the app opens on the new version's code at the same address. Signed-in data still needs a connection.
• Safe updates: after a deploy, an open app shows "A new version is ready." with an Update button. It checks on each page load and every hour, and never reloads by itself. Once someone updates in one tab, the other open tabs reload into the new version too, except pages that show the update themselves (see Make it installable).

Admins see install numbers on the admin dashboard. For when an app should use this, see Make it installable.

Turn it on or off

The PWA is a switchable feature, id pwa, and the only one that is off by default, so a plain website gets no service worker. It needs no other feature. Turn it on in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    on: ['pwa'],
};

The choice is read at build time, so it takes a new build and deploy.

When it is off, the build writes no manifest, icons or service worker, the install card and update bar never show, the dashboard has no App installs numbers, and the trackPwaEvent function is not built. To turn it off again, remove 'pwa' from on and deploy: on each visitor's next visit the site removes its service worker and stored files, so everyone gets the plain website. An icon already on a home screen still opens the site, as a normal web page.

Set it up

1. Name it in src/custom/pwa.ts. Anything you leave out keeps the default:

   export const CUSTOM_PWA: Partial<PwaConfig> = {
       name: 'Sanskrit for Kids',
       shortName: 'Sanskrit',
       description: 'Learn Sanskrit through play.',
       themeColor: '#e8590c',
       backgroundColor: '#ffffff',
       startUrl: '/learn',
   };

   Key	Default	Used for
   name	Arc CMS	The install dialog and the app switcher.
   shortName	Arc CMS	Under the home-screen icon. Keep it to about 12 characters. Set it whenever you set name: left out, it stays Arc CMS.
   description	Empty	The manifest's description.
   themeColor	#1d47a3	The browser bar and phone status bar, and the install card's accent.
   backgroundColor	#ffffff	The splash screen while the app opens.
   startUrl	/	The page the home-screen icon opens.
   navigationTimeoutSeconds	4	How long a page waits for the network before the stored copy opens, from 1 to 30 seconds. Lower it for an app often on a network without internet, such as a kiosk on a closed Wi-Fi: each start then waits less. Too low, and a slow connection gets the stored copy instead of fresh content.
   icon	src/custom/pwa-icon.svg or .png, else Arc CMS's	The image every icon size is made from, an .svg or .png named by its path from the project folder, such as src/custom/brands/acme/icon.svg. For an app with a different icon per brand. A file that is not there stops the build.
   appleIcon	padded	The iPhone and iPad home-screen icon. padded puts your image on a white tile with a margin, which suits a logo on a transparent background. fill makes it fill its square with no margin, for an icon that is already a full coloured square (otherwise it shows as a smaller square on white). Transparent corners then show backgroundColor.
   routeCode	visited	Which screens' code is stored when the app installs or updates: visited (only what every page needs, the rest as it is first opened), app (every screen outside the admin area) or all. See Make it installable.

   The defaults are in src/app/core/pwa/pwa-config.ts. The installed app opens in its own window without the browser bar (standalone), with the whole site in scope.

2. Add one square icon, at least 512 by 512 pixels, as src/custom/pwa-icon.svg or src/custom/pwa-icon.png (the SVG wins if both exist), or anywhere in the project with icon naming it. Every size is made from it at build time, including the iPhone icon and the "maskable" one Android crops to a circle or rounded square, so keep the important part within the middle 80%. Without one, a plain "Arc" icon is used. The site's favicon is not changed.

3. Build and deploy (see Deploy). Deploy the functions too, for the install numbers.

Use it

The install card

<arc-install-prompt /> shows what fits each browser:

Not now hides it on that device for 30 days. Arc CMS's own member dashboard (/user/dashboard) shows it at the top; an app that replaces that page places it itself.

The card carries its own styles and icons (inline SVG, no Bootstrap or Font Awesome classes), so it looks the same inside a Shadow DOM host. Its accent is themeColor.

iPhone and iPad read the home-screen icon and name from the page itself, not the manifest, so the build also adds an apple-touch-icon link and the apple-mobile-web-app-title (the short name) to every page. By default that icon is your image shrunk onto a white tile; with appleIcon: 'fill' it fills its square instead (see the table above).

Install numbers

With the PWA on, the admin dashboard shows App installs: installs in the last 30 days by platform (Android, iPhone and iPad, computer), the install rate (people whose record says they installed, out of everyone with a record), and openings from the home screen in the last 30 days (each device once a day).

The browser reports four events to the trackPwaEvent function: prompt_shown, installed, dismissed and opened_installed. prompt_shown and installed count once per device, opened_installed once a day per device, and dismissed each time someone declines. iPhone has no install event, so the first opening from the home screen counts as the install. Visitors who are not signed in are counted too, since people often install before signing in.

Test it

A service worker runs only on https or localhost, and only in a production build: npm run dev has none. To try it on your computer, build and serve the browser build:

npm run build

npx vite preview --port 5190 --outDir dist/client

Open http://localhost:5190. In Chrome's DevTools, Application: Manifest shows the name and icons, Service workers shows sw.js running, and the install icon appears in the address bar. On a phone, the site needs a real https address: deploy it and open it there.

Extend it

• Show the install card on your own page: import InstallPromptComponent from src/shared/components/install-prompt/install-prompt.component.ts and put <arc-install-prompt /> in the template.
• Know whether the app runs installed: PwaService (src/app/core/pwa/pwa.service.ts) has installed(), showInstall(), installMode() and updateReady().
• Draw your own install card or sheet: PwaService's install side is the supported way. See Make it installable.
• Show the update yourself: an app that lives on full-screen pages can show "a new version is ready" where it suits, with updateReady(), checkForUpdate() and applyUpdate(), and a route flag that keeps Arc CMS's bar away. See Make it installable.

What it stores

Cloud Function: trackPwaEvent (callable, built only with the feature). One caller counts at most 30 events an hour; the rest are accepted and not counted. The build writes sw.js, the manifest and the icons into the site; no Storage files are used.

Who can do what

• Visitors, signed in or not, report install events through trackPwaEvent.
• Only admins can read PwaStats; only the function writes it.
• The pwa field on a record is written by the function and readable by the person and admins, like the rest of the record.

Troubleshooting