docs: add PWA cookbook (#1747)

Co-authored-by: Michel EDIGHOFFER <edimitchel@gmail.com>

README.md

@@ -117,6 +117,10 @@ Elk uses [Vitest](https://vitest.dev). You can run the test suite with:
 nr test
 ```
 
+## 📲 PWA
+
+You can consult the [PWA documentation](https://docs.elk.zone/docs/pwa) to learn more about the PWA capabilities on Elk, how to install Elk PWA in your desktop or mobile device and some hints about PWA stuff on Elk.
+
 ## 🦄 Stack
 
 - [Vite](https://vitejs.dev/) - Next Generation Frontend Tooling
@@ -129,7 +133,7 @@ nr test
 - [Iconify](https://github.com/iconify/icon-sets#iconify-icon-sets-in-json-format) - Iconify icon sets in JSON format
 - [Masto.js](https://neet.github.io/masto.js) - Mastodon API client in TypeScript
 - [shiki](https://shiki.matsu.io/) - A beautiful Syntax Highlighter
-- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update and push notifications
+- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update, Web Push Notifications and Web Share Target API
 
 ## 👨‍💻 Contributors
 

docs/content/1.guide/3.contributing.md

@@ -50,4 +50,4 @@ nr test
 - [Iconify](https://github.com/iconify/icon-sets#iconify-icon-sets-in-json-format) - Iconify icon sets in JSON format
 - [Masto.js](https://neet.github.io/masto.js) - Mastodon API client in TypeScript
 - [shiki](https://shiki.matsu.io/) - A beautiful Syntax Highlighter
-- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update and push notifications
+- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update, Web Push Notifications and Web Share Target API

docs/content/80.pwa.md

@@ -0,0 +1,131 @@
+# PWA
+
+Elk provides a PWA (Progressive Web App) that can be installed on your desktop/device. This allows you to use Elk as a native app on your device, and it will work offline.
+
+The main goal of the PWA is to provide a native app experience on mobile devices with Web Push Notifications and Web Share Target API capabilities.
+
+Web Share Target will allow you to share content from other apps to Elk in mobile browsers.
+
+## Mobile Support
+
+Some mobile browsers will allow you to install the PWA as a native app, and some others will only allow you to add the PWA to your home screen.
+
+If you're using a mobile browser that supports the PWA installation, you will see a banner at the bottom of the screen with the option to install the PWA.
+
+If the browser also supports [beforeinstallprompt](https://web.dev/customize-install/) event, ElK will show a prompt (on the right aside on wide screens, or at top on small screens) to allow you to install the PWA directly.
+
+If the browser doesn't support the PWA installation, check following entries:
+
+### Safari iOS
+
+Right now, you cannot use Web Push Notifications on Safari mobile browsers, since it doesn't support the Web Push API yet at operating system level.
+
+You can check the status of the Push API on Safari mobile browsers on [this page](https://caniuse.com/notifications).
+
+Visit also [this site](https://firt.dev/notes/pwa-ios/) to check the status of PWA Capabilities on Safari mobile browsers.
+
+To install a Progressive Web App (PWA) on Safari, follow these steps:
+- Tap the "Share" icon at the bottom of the screen.
+- Scroll down and tap "Add to Home Screen".
+- Customize the name of the app (if desired) and tap "Add".
+- The PWA should now appear on your home screen.
+
+### Firefox
+
+To install a Progressive Web App (PWA) on Firefox, follow these steps:
+- Look for the install button or icon, usually located in the address bar or in a prompt that appears on the screen.
+- Click on the install button or icon and follow the prompts to complete the installation.
+- If you don't see an install button or icon, you can look for the PWA in the Firefox menu. Click on the three horizontal lines in the top/bottom right corner of the browser window to open the menu, then click on "Install" option.
+
+### Chromium based browsers
+
+To install a Progressive Web App (PWA) on Chromium based browsers, such as Google Chrome, Microsoft Edge, or Brave, follow these steps:
+- Click on the menu button (three vertical dots) at the top right corner of the screen.
+- Select "Install Elk as app" or "Install Elk to Home screen".
+- Customize the name of the app (if desired) and click "Install" or "Add".
+- The PWA should now appear on your device's home screen or in your app drawer.
+
+## PWA Configuration in Elk project
+
+By default, Elk will enable the PWA integration, but can be disabled by setting `VITE_DEV_PWA` to `false` in your `.env` file.
+
+You can find the configuration options for the PWA in the [config/pwa.ts](https://github.com/elk-zone/elk/blob/main/config/pwa.ts) module.
+
+### PWA Web Manifest
+
+Right now, there is no support for web manifest internationalization and theme color in any browser, we're using a custom module to generate web manifests for theme color and language variants.
+
+Elk will generate 2 web manifests per locale, one for light theme and one for dark theme.
+
+You can check web manifest generation on [modules/pwa/i18n.ts](https://github.com/elk-zone/elk/blob/main/modules/pwa/i18n.ts) module.
+
+### PWA UI Components
+
+Elk will provide a set of UI components to allow you to customize the PWA installation prompt on browsers with [beforeinstallprompt](https://web.dev/customize-install/) support.
+
+You can find the PWA installation prompt in the [PwaInstallPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaInstallPrompt.client.vue) component: will be shown on the right aside on wide screens, or at top on small screens.
+
+Elk is using prompt for update strategy, so the PWA prompt for update will be shown only if there is a new version of Elk available.
+
+On small screens, the PWA prompt for update will be shown as a button on the head, you can find it in [PwaBadge](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaBadge.client.vue) component.
+
+On wide screens, the PWA prompt for update will be shown as a prompt on the right aside, you can find it in [PwaPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaPrompt.client.vue) component.
+
+PWA prompt for update will take preference over PWA installation prompt, so if there is a new version of Elk available, the PWA prompt for update will be shown instead of the PWA installation prompt.
+
+All previous UI components don't have any logic, all them will use the logic provided by the [PWA plugin](https://github.com/elk-zone/elk/blob/main/plugins/pwa.client.ts).
+
+### Service Worker
+
+You can find Elk custom service worker in [service-worker folder](https://github.com/elk-zone/elk/blob/main/service-worker), it provides:
+- [Prompt for update strategy](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L14).
+- [Web Push Notifications](https://github.com/elk-zone/elk/blob/main/service-worker/web-push-notifications.ts): [push notifications](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L105) and [push notification click](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L106).
+- [Web Share Target API](https://github.com/elk-zone/elk/blob/main/service-worker/share-target.ts): [share target registration](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L107).
+
+### Push Notifications Subscription Logic
+
+Elk will allow you to send push notifications to your users, you can find the logic for Web Push Notifications subscription [composables/push-notifications folder](https://github.com/elk-zone/elk/blob/main/composables/push-notifications).
+
+There is a limitation on browsers about registering multiple Web Push Notifications: you can only subscribe to one push service per browser per application: trying to register multiple push subscriptions will be treated as spam by the browser.
+
+If you try to register multiple push subscriptions, the browser will throw an error, and you will need to unregister the previous push subscription before registering a new one.
+
+### Debugging PWA in development
+
+To debug the PWA in development, you will need to run `dev:pwa` or `dev:mocked:pwa` script.
+
+Running one of previous scripts will start a development server with the PWA enabled: you can review the web manifests and debug the service worker in your browser, use any Chromium based browser, since we're registering the service worker using `type: 'module'`.
+
+You can debug Web Push Notifications in desktop and mobile browser and Web Share Target in your mobile device, using the same URL as the development server.
+
+Right now, we can only debug on Android Chrome mobile browsers:
+- Web Push Notifications: you don't need to install de PWA, just enable the notifications in the browser on notifications page or web push notifications settings page.
+- Web Share Target: you need to install the PWA, and then you can share content from other apps to Elk.
+
+### Debugging PWA in mobile browsers
+
+To debug the PWA service worker in your mobile browser, you will need to:
+1) Enable development options in your Android device:
+  - Go to "Settings" on your device.
+  - Scroll down to "About phone" and tap it.
+  - Locate the "Build number" and tap it repeatedly (usually 7 times) until you see a message saying that you have enabled developer options.
+  - Go back to "Settings" and you should now see "Developer options" listed.
+  - Tap on "Developer options" and you can enable various settings such as USB debugging, mock locations, and more.
+2) Connect your Android device to your computer using a USB cable.
+3) Enable USB debugging in your Android device:
+  - Go to "Settings" on your device.
+  - Scroll down to "Developer options" and tap it.
+  - Enable "USB debugging".
+  - Confirm the prompt on your device to allow USB debugging.
+  - Open Chrome/Edge browser in your device.
+4) Open Chrome on your computer and go to `chrome://inspect/#devices`.
+  - Elk application should be listed in the "Remote Target" section after a few seconds (navigate to any page).
+  - Enter `http://localhost:5314` in the open in a new tab input and click Open button.
+  - Click on the "Inspect" button to open the DevTools.
+5) Remember to remove the service worker from your device browser using dev tools once you finish testing the service worker:
+  - Go to `Application > Storage`, you should check following checkboxes:
+    - Application: `[x]` Unregister service worker
+    - Storage: `[x]` Local and session storage `[x]` IndexedDB
+    - Cache: `[x]` Cache storage and `[x]` Application cache
+  - Click on Clear site data button
+  - Go to `Application > Service Workers` and check the current service worker is missing or has the status deleted or reduntant.