Qwik PWA 📱

Turn your Qwik Application into an offline compatible PWA (Progressive Web Application) using Workbox but without the hassle.

Installation

npm install --save-dev @qwikdev/pwa

vite.config.ts:

import { qwikPwa } from "@qwikdev/pwa";

export default defineConfig(() => {
  return {
    define: {
      // (optional) enables debugging in workbox
      "process.env.NODE_ENV": JSON.stringify("development"),
    },
    plugins: [
      qwikCity(),
      qwikVite(),
      // The options are set by default
      qwikPwa({
        /* options */
      }),
    ],
  };
});

src/routes/service-worker.ts:

import { setupServiceWorker } from "@builder.io/qwik-city/service-worker";
import { setupPwa } from "@qwikdev/pwa/sw";

setupServiceWorker();

+setupPwa();

- addEventListener("install", () => self.skipWaiting());

- addEventListener("activate", () => self.clients.claim());

- declare const self: ServiceWorkerGlobalScope;

By default, your application will be auto-updated when there's a new version of the service worker available and it is installed: in a future version, you will be able to customize this behavior to use prompt for update:

import { setupServiceWorker } from "@builder.io/qwik-city/service-worker";
import { setupPwa } from "@qwikdev/pwa/sw";

setupServiceWorker();
setupPwa("prompt");

public/manifest.json:

"background_color": "#fff",
+ "theme_color": "#fff",

For more information, check the following pages:

src/components/router-head/router-head.tsx:

// PWA compatible generated icons for different browsers
import * as pwaHead from "@qwikdev/pwa/head";

export const RouterHead = component$(() => {
    ...
      {pwaHead.meta.map((l) => (
        <meta key={l.key} {...l} />
      ))}
      {pwaHead.links.map((l) => (
        <link key={l.key} {...l} />
      ))}
    ...

Make sure you remove the <link rel="icon" type="image/svg+xml" href="https://github.com/QwikCommunity/pwa/blob/main/favicon.svg" /> line in your router-head file.

Now your application is PWA-friendly.

Precache

One feature of service workers is the ability to save a set of files to the cache when the service worker is installing. This is often referred to as "precaching", since you are caching content ahead of the service worker being used. Chrome for Developers

Assets

Assets like js modules generated by qwik (q-*.js), images, public/ assets, or any file that's emitted in the dist/ directory by the build step would be precached when the service worker instantiates, so the plugin makes sure it provides the best client-side offline experience.

Routes

By default in this plugin, every route that does not include params (/ or /demo/flower) is precached on the first run of the application when the browser registers the service worker.

For the rest of the defined routes (routes with params like /dynamic/[id], SSG routes, or API routes), they are not precached, but there are workbox navigation routes defined that would cache them on-demand and per request, the reason is precaching too many assets on the first run would cause a laggy experience for the user, especially when these kind of routes have the potential to generate so many more files.

Imagine there's an SSG /blog/[id] route that generates 120 blog posts, in this case, fetching 120 pages of blog posts in the application startup would not seem ideal.

Solution

Just fetch the desired page or asset so it gets cached for later uses.

fetch("/blog/how-to-use-qwik");

API Routes

For API routes and any other routes that do not meet the conditions mentioned above, there's a Network-First handler.

Manifest

The plugin would generate all of the adaptive icons needed for different devices with different ratios in manifest.json based on your main icon in the build process using @vite-pwa/assets-generator.

Screenshots

For full PWA compatibility, you can put your screenshots with the following pattern in the public/manifest.json file.

    ...
    "screenshots": [
        {
            "src": "/screenshot.png",
            "type": "image/png",
            "sizes": "862x568"
        },
        {
            "src": "/screenshot.png",
            "type": "image/png",
            "sizes": "862x568",
            "form_factor": "wide"
        }
    ]

For beautiful screenshots, you can use Progressier Screenshots Generator.

Cloudflare deployment

PNPM

Need set resolutions w/ "sharp": "0.32.6" on package.json;
It is necessary to create a file npm-lock.yaml by pnpm install.

Bun

Need set resolutions w/ "sharp": "0.32.6" on package.json;
It is necessary to create a file bun.lockb by bun install.
Set ENV BUN_VERSION=1.0.5 (or higher) in Cloudflare. Cuz the default version of Bun - 1.0.1 doesn't work.

QwikCommunity / pwa

readme