docs: add PWA cookbook (#1747)
Co-authored-by: Michel EDIGHOFFER <edimitchel@gmail.com>
This commit is contained in:
Joaquín Sánchez
GitHub
parent
fbe1463f17
commit
3118ed6012
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
131
docs/content/80.pwa.md
Normal file
131
docs/content/80.pwa.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue