docs: improve the "getting started" section

[ZYinMD]

It seems the first chapter of Doc, Gettings Started, is meant to tell people "how to add this plugin if you already have a vite project". However, it only covers adding the plugin and doesn't cover sw registration, so it doesn't really get people started.

Note: I'm not sure if what I added was officially correct. It just worked for me.

[netlify[bot]]

✅ Deploy Preview for vite-plugin-pwa ready!

Name	Link
🔨 Latest commit	55d2f69a9d8362645387f830b28944cd6f7c62b8
🔍 Latest deploy log	https://app.netlify.com/sites/vite-plugin-pwa/deploys/62680604401daf0008783c23
😎 Deploy Preview	https://deploy-preview-274--vite-plugin-pwa.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[userquin]

@ZYinMD thx, maybe it will be better to add a new entry on that page called Client Runtime below Setup adding 5 links to (with some prose):

• https://vite-plugin-pwa.netlify.app/guide/prompt-for-update.html#runtime
• https://vite-plugin-pwa.netlify.app/guide/auto-update.html#runtime
• https://vite-plugin-pwa.netlify.app/guide/inject-manifest.html#runtime-1
• https://vite-plugin-pwa.netlify.app/guide/inject-manifest.html#runtime-3
• https://vite-plugin-pwa.netlify.app/frameworks/#usage

We can also add the links when using some framework in the same Client Runtime entry: the links should be to https://vite-plugin-pwa.netlify.app/frameworks/vue.html and so on.

[ZYinMD]

Hi @userquin , I'm not familiar enough with all the contents, so I'll leave the decision up to you. However, as a user of this plugin, I generally feel the whole doc is quite confusing overall.

In my opinion, the natural order of steps for a beginner to progressively opt into PWA is:

1. get sw registered
2. precache
3. make app installable
4. runtime caching (routes and strategies)
5. skipwait / clientclaim
6. prompt to reload / auto update

In my mind, this order is 1. from easy to hard, 2. from important to less important, 3. from popular goals to less popular goals.

However, the doc seems to think in a different order. For instance, the first 3 links you just mentioned are all located under "prompt to reload / auto update" sections. If a reader simply wants to get started, and has no interest in prompting reload, they may skip those sections, and get lost in finding how to register the sw.

Another reason why the the doc was overall confusing to me was the word choice of "setup" and "runtime". These 2 words are empty words without real meanings, so I didn't notice them, or they didn't register in my brain. It took me hours before I finally realized that all sections are broken into setup and runtime.

Another problem is the word runtime sometimes means "how to register sw", and some other times means "code inside sw". Meanwhile the workbox doc never used this word, except in "precache vs runtime cache".

Two things you might consider:

1. In the "Getting Started" section, add some notes in the beginning to tell people that "hey, when you read this doc, look for the setup and runtime headings. Almost all sections are broken into these two headings, where setup is about your vite config, and runtime is about how to register your sw from Window, or how to write code inside your sw.
2. change all setup and runtime headings into something else, e.g. vite config and sw registration and in your sw code. This may improve reader experience.

[userquin]

@ZYinMD I'll refactor the docs using your feedback, I'll ping you to check the new docs once changed using the Netlify preview on this PR https://github.com/antfu/vite-plugin-pwa/pull/304

[userquin]

@ZYinMD here the first version of the index guide (ignore the last entry Features): https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/

[userquin]

@ZYinMD the new docs PR ready to review, I've udpated all entries, if you want to check it

[ZYinMD]

Hi @userquin, in my previous comments in this thread, my main complaint was that "the whole doc was overall confusing for new users". Now I look at the 304 preview and found the doc got a big overhaul. I only skimmed through it superficially but it seems to be much more friendly than before. I'm sure you did a ton of work and thanks very much!

Is preview 304 meant to go with v0.12.0? I found things that were never mentioned in the previous doc. For example, it's the first time I saw the 4 types of injectRegister. I've been using v0.12.0 previously, but using the virtual model to register the sw was the only way I knew.

[userquin]

@ZYinMD thx

The new docs are valid also for 0.12.0 (except for the new features in development) but there is a bug about the injectRegister option, it is broken, but should be fixed in the next patch (0.12.1), fixed in #306.

The usage of injectRegister was not covered in old docs and we included some hints about using the virtual modules (Import Virtual Modules entries on new docs), mainly due to the bug, for example here https://vite-plugin-pwa.netlify.app/guide/auto-update.html#automatic-reload (check the hint).

EDIT: I guess this can be closed...

EDIT 2: you can try it with autoUpdate behavior and without using virtual modules just adding the claims stuff to the workbox entry on the plugin options, check this comment https://github.com/antfu/vite-plugin-pwa/issues/307#issuecomment-1159380341 (I'll add the hint on the new docs if not using 0.12.1+)

EDIT3: included fix on guide index http://localhost:3000/guide/#configuring-vite-plugin-pwa

[ZYinMD]

Hi @userquin , I didn't get a chance to test the new doc with real code, but here's some things I noticed:

(Same as last time, my goal is "getting started with a working PWA", and my focus is still the confusion and friction during onboarding)

1. in how to set my vite config, VitePWA({ registerType: 'autoUpdate' }) is used. Does that register the sw? If no, why do I need it? If yes, is it the same as injectRegister: 'auto'? If they're the same, why are they called different names? Also, in the injectRegister doc, there's no configuration code example that I can copy, so I don't know how to invoke injectRegister, which is why I'm confused about whether it's the same as registerType.

2. In how to enable sw in dev, devOptions: { enabled: true } is used. I'm not sure if it's enough, you could do a test. In my last PR, my impression was it's not enough without setting type: 'module'.

3. In configure injectManifest, the doc doesn't mention where the plugin look for the sw source. There's one sentence implying public/sw.js is the default location it looks, I'm not sure if that's true, but if yes, I think this should be mentioned more explicitly.

   Meanwhile, customizing sw source location appeared very late, at the page bottom, under "typescript support", but I shouldn't need to be a typescript user to know I can customize the filename and location, so this should appear up top.

   Actually, public/sw.js is a confusing location to begin with. Usually public isn't a place where bundlers look for source code, so people will think "how will my workbox code get compiled"? Overall, I think it's better to just always mandate the filename and srcDir in vite config when using injectManifest, it's good for everybody. Even it's not required, I'd still vote for writing the doc in a way that makes it look required.

4. In the introduction of Frameworks, I think it's very important to tell readers that they're not required to use the framework specific stuff. Example:

   This plugin is Framework-agnostic. With previous guides, you can have a working PWA no matter which framework you use. However, if you need feature X, feature Y, or feature Z, this plugin exports some additional modules for each framework.

   95+% people are framework users, and it'll be very daunting if they think they have to learn into the framework specifics. Frankly, I read the react section and I can't understand it, so it's important for me to know it's not something I must understand.

[userquin]

@ZYinMD ok I'll try to refactor it, but due to amount of concepts, it is hard talk about things that are tighly coupled but their meaning are completly distinct.

Maybe I can remove the Service Worker Strategies And Behaviors adding the content on index guide below Service Worker entry.

For example, in your first point:

• Does that register the sw? NO, you should finish reading the Getting Started, I cannot explain everything in one sentence. Can you just read the 3 first entries in the guide?
• If yes, is it the same as injectRegister: 'auto'? If they're the same, why are they called different names?: registerType and injectRegister are 2 distincts things, former is related to how the sw will work on the browser when there is a new version of your app, and later is related to how the plugin will register the sw in the browser: both options are related but for distinct purposes.

Give me some time...

[ZYinMD]

edited

[userquin]

@ZYinMD do you have discord account?

[userquin]

Hi @userquin , I didn't get a chance to test the new doc with real code, but here's some things I noticed:

(Same as last time, my goal is "getting started with a working PWA", and my focus is still the confusion and friction during onboarding)

1. in [how to set my vite config](https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/#configuring-vite-plugin-pwa), `VitePWA({ registerType: 'autoUpdate' })` is used. Does that register the sw? If no, why do I need it? If yes, is it the same as `injectRegister: 'auto'`? If they're the same, why are they called different names? Also, in the [injectRegister doc](https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/register-service-worker.html), there's no configuration code example that I can copy, so I don't know how to invoke injectRegister, which is why I'm confused about whether it's the same as `registerType`.

• registerType will NOT be used to register the sw
• you need it because the default registerType is prompt
• registerType and injectRegister are not the same thing
• about register-service-worker, the configuration option is just a string, maybe I can add a simple example on each entry, it is just a string? If you need a basic example, just use the configuration

2. In how to [enable sw in dev](https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/#configuring-vite-plugin-pwa), `devOptions: { enabled: true }` is used. I'm not sure if it's enough, you could do a test. In [my last PR](https://github.com/antfu/vite-plugin-pwa/pull/273), my impression was it's not enough without setting `type: 'module'`.

• I'll check it, but should work using generateSW strategy, workbox-build should generate the js file

3. In [configure injectManifest](https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/inject-manifest.html#custom-service-worker), the doc doesn't mention where the plugin look for the sw source. There's one sentence implying `public/sw.js` is the default location it looks, I'm not sure if that's true, but if yes, I think this should be mentioned more explicitly.

• the plugin configuration using injectManifest strategy only requires the stuff to locate the custom service worker, you cannot provide anything related to the sw source code, the sw is just the logic on it
• the default localtion is src/sw.js, you've the dts file with jsdocs

   Meanwhile, [customizing sw source location](https://deploy-preview-304--vite-plugin-pwa.netlify.app/guide/inject-manifest.html#plugin-configuration-2) appeared very late, at the page bottom, under "typescript support", but I shouldn't need to be a typescript user to know I can customize the filename and location, so this should appear up top.

• you've the dts file with jsdocs
• if you're using JavaScript you should put the service worker on the public folder, the sw will not be compiled by the bundler, or maybe on the assets folder, but then this plugin will not work (will not be able to locate the assets, it will contain the hash)

   Actually, `public/sw.js` is a confusing location to begin with. Usually `public` isn't a place where bundlers look for source code, so people will think "how will my workbox code get compiled"? Overall, I think it's better to just always mandate the `filename` and `srcDir` in vite config when using injectManifest, it's good for everybody. Even it's not required, I'd still vote for writing the doc in a way that makes it look required.

• just read previous response, the bundler will not build/compile the sw

4. In the [introduction of Frameworks](https://deploy-preview-304--vite-plugin-pwa.netlify.app/frameworks/#getting-started), I think it's very important to tell readers that they're not required to use the framework specific stuff. Example:
   > This plugin is Framework-agnostic. With previous guides, you can have a working PWA no matter which framework you use. However, if you need feature X, feature Y, or feature Z, this plugin exports some additional modules for each framework.

• ok, we can include some entry for the features

   95+% people are framework users, and it'll be very daunting if they think they have to learn into the framework specifics. Frankly, I read the react section and I can't understand it, so it's important for me to know it's not something I must understand.

• can you elaborate? the main reason is when you use the prompt for new content strategy: you need to show a toast/dialog (like the docs in this repo) and when the user clicks the reload button you need to send the corresponding message to the sw to activate the new sw version. How can you show that toast/dialog using react? Simply, use the virtual module for react provided by this plugin (it will expose a reactive prop from react you'll use to show toast/dialog)

Maybe we can chat on gmail or in discord.

[userquin]

@ZYinMD I have included some links on vite-plugin-pwa entry on index guide: as you can see, before begining you're asking things that are explained later. If you check the Service Worker Strategies And Behaviors it links to the index guide, it is a graph ;)

[userquin]

@ZYinMD about the devOptions, it is working:

[userquin]

@ZYinMD thx for the PR, closing since the changes are already on the docs: feel free to open new one if you have more suggestions