search

vite-pwa / nuxt

Zero-config PWA Plugin for Nuxt 3
https://vite-pwa-org.netlify.app/frameworks/nuxt
MIT License
449 stars 22 forks source link

Need clarification on $pwa properties #39

Open NBaron opened 1 year ago

NBaron commented 1 year ago

Hi all,

First, thank you for your time and for sharing this Nuxt module. It would be great to clarify the meaning/usage of $pwa.

export interface PwaInjection {
  isInstalled: boolean
  showInstallPrompt: Ref<boolean>
  cancelInstall: () => void
  install: () => Promise<void>
  swActivated: Ref<boolean>
  registrationError: Ref<boolean>
  offlineReady: Ref<boolean>
  needRefresh: Ref<boolean>
  updateServiceWorker: (reloadPage?: boolean | undefined) => Promise<void>
  cancelPrompt: () => Promise<void>
  getSWRegistration: () => ServiceWorkerRegistration | undefined
}

I tried to understand by looking at the doc and the playground, but I can't get a full picture. Here is what I understand so far, and some related questions.

Suggestions

May I suggest:

  1. To add a sequence diagrams to the documentation showing at least install and update process (I can help with this once I understand better).
  2. To improve the naming consistency (I can also help with this once the nomenclature is confirmed):
    • ServiceWorker in place of sw or SW.
    • 'is' or 'has' prefix for state.
    • Clarify what is 'Prompt'.

Thanks in advance for your help.

userquin commented 1 year ago

The service worker lifecycle is complex, we may have 2 service workers when new version detected.

Here is what I understand so far, and some related questions.

* isInstalled: true when PWA is installed on the device.

PWA installed, also TWA, but not all cases, check link in the template

* showInstallPrompt: _This seems to be a state, but what is impacting its value?

this flag is to call browser/native prompt: check https://elk.zone app on browser, right aside (next popup will be shown only when this flag is true)

imagen

* cancelInstall: _What does this method?_

this method only force to remove the custom install popup, it is the dismiss button in previous screenshot: once cancelInstall called showInstallPrompt will never be true again (will store false in local storage), sometimes ppl just want browser/native install behavior

if installation cancelled from browser/install prompt, showInstallPrompt will be activated when required

* install: Install the PWA. _What if called while already installed?_

nothing happens, the method is just Promise.resolve(): the plugin will change it when received beforeinstallprompt event

calling this method will just call browser/native install logic

* swActivated: state of the activation of the service worker.

will be true when the new/current sw is active: check the logic in the template, onRegisteredSW callback

* registrationError: indicate if an error occurred during SW registration. _How to get the error?_

not exposed: we can expose it in onRegistrationError (I need to check if we can access it from active sw)

* offlineReady: _What does it mean exactly? What is impacting its value?_

flag only fired in first sw install: you can use it to show your app is ready to work offline when using workbox precaching

* needRefresh: _What does it mean exactly? What is impacting its value?

this flag will be true when new sw detected and ready to be activated: only when using prompt register type

* updateServiceWorker: Method to update SW when an update is pending. _Is it related to needRefresh?

yes, once needRefresh is true, the UI should bind button click to this method to activate the new service worker (will claim all openened clients, tabs and browser instances, controlled by previous installed service worker)

* cancelPrompt: _What does this method? Is it related to cancelInstall?_

no, it is related to offlineReady and needRefresh: when new sw detected, the ui should show a prompt, this method will switch these 2 flags to false

* getSWRegistration: Get the SW registration.