pwa-ready

Make any web project PWA-ready in seconds with generated PWA assets, installability checks, auto-fix, and a customizable install popup UI.

What Is A PWA?

A Progressive Web App is a web application that can be installed, launched from the home screen or app launcher, load quickly, and continue to work during poor or missing network conditions. A production PWA typically needs a valid web manifest, service worker, installable icons, HTTPS, correct metadata, and a tested offline fallback.

Why Install UI Matters

Browsers decide when the native install prompt is available, but product teams still need a clear, branded entry point that explains the value of installing. pwa-ready generates a custom popup or banner that listens for beforeinstallprompt, stores the deferred browser prompt, and connects it to your own install button.

Screenshots

Install

npm install --save-dev pwa-ready

Run without installing:

npx pwa-ready init
npx pwa-ready generate --icon ./logo.png

Commands

pwa-ready init
pwa-ready generate
pwa-ready audit
pwa-ready fix
pwa-ready watch

Options

--config <path>
--verbose
--silent
--dry-run
--icon <path>
--position bottom-left
--radius 20
--bg "#000"
--ui card
--strategy stale-while-revalidate
--concurrency 8

Generated Files

public/
  manifest.json
  service-worker.js
  offline.html
  icons/
    icon-72x72.png
    icon-96x96.png
    icon-128x128.png
    icon-192x192.png
    icon-256x256.png
    icon-512x512.png
  pwa/
    install.html
    install.css
    install.js
    register-sw.js

Static HTML projects without a public/ directory write these files at the project root so /manifest.json and /service-worker.js are served from the origin root.

Config

import type { PwaConfig } from "pwa-ready";

const config: PwaConfig = {
  name: "Acme Dashboard",
  shortName: "Acme",
  description: "Installable operations dashboard.",
  themeColor: "#0a0a0a",
  backgroundColor: "#ffffff",
  icons: {
    source: "./logo.png"
  },
  ui: {
    enabled: true,
    position: "bottom-left",
    radius: 20,
    background: "#0a0a0a",
    textColor: "#ffffff",
    buttonColor: "#ff4d00",
    layout: "card"
  },
  serviceWorker: {
    strategy: "stale-while-revalidate"
  }
};

export default config;

Framework Support

pwa-ready detects and patches common entry points:

index.html
public/index.html
app/layout.tsx
src/app/layout.tsx
pages/_document.tsx
src/pages/_document.tsx

It works with Next.js, React, Vue, Vite, and static HTML projects. The generated files are framework-neutral and served as static assets.

API Usage

import { auditProject, fixProject, generateProject, initProject } from "pwa-ready";

await initProject(process.cwd());
await generateProject(process.cwd(), {
  icon: "./logo.png",
  strategy: "network-first",
  ui: "glass"
});

const audit = await auditProject(process.cwd());
if (!audit.passed) {
  await fixProject(process.cwd());
}

Service Worker Strategies

pwa-ready generate --strategy cache-first
pwa-ready generate --strategy network-first
pwa-ready generate --strategy stale-while-revalidate

Audit

pwa-ready audit

Checks manifest validity, required icon sizes, service worker files, registration injection, install UI assets, HTML metadata, and HTTPS installability requirements.

Fix

pwa-ready fix

Runs an audit, regenerates missing assets, injects missing tags/scripts, then audits again.

Watch

pwa-ready watch --icon ./logo.png

Regenerates PWA assets when config, public assets, or app entry files change.

Release

This package is configured for semantic-release and conventional commits. CI runs install, lint, tests, and build across supported Node.js versions.