elk/docs/content/80.pwa.md

# 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.

### Other borwsers on iOS

Browsers on iOS other than Safari (like Chrome) are very limited on PWA functionalities. Besides Web Push Notifications (like in Safari) not even PWA installation is supported.

If you are using one of these browsers and want to add Elk to your homescreen, you will have to use Safari and follow the instructions above.

### 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`.
  - Your device should be listed in the "Remote Target" section after a few seconds (if not, open Chrome/Edge and navigate to any page).
  - Click the "Port forwarding..." button and type "5314" into the "Port" input and "localhost:5314" into the "IP address and port" input, then press "Done".
  - Enter `http://localhost:5314` in the "Open tab with url" input and click the "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.
6) Disable port forwarding: open the "Port forwarding..." modal again on the `chrome://inspect/#devices` page and either uncheck the "Enable port forwarding" option or remove the entry from the list and click "Done".