PWA

Nimbus provides a Progressive Web App (PWA) that can be installed on your desktop/device. This allows you to use Nimbus 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 allows you to share content from other apps to Nimbus in mobile browsers.

Mobile Support

Some mobile browsers allow you to install the PWA as a native app. Others only allow you to add the PWA to your home screen.

If you're using a mobile browser that supports 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 the beforeinstallprompt event, Nimbus displays a prompt (on the right side on wide screens, or at top on small screens) to allow you to install the PWA directly.

If the browser doesn't support PWA installation, check the following sections.

Safari iOS

Right now, you can't use Web Push Notifications on Safari mobile browsers, since it doesn't support the Web Push API yet at operating system level.

See caniuse to see the status of the Push API in Safari for mobile and firt.dev to see the status of PWA capabilities in Safari for mobile.

To install a PWA on Safari, follow these steps:

  1. Tap the "Share" icon at the bottom of the screen.
  2. Scroll down and tap "Add to Home Screen".
  3. Customize the name of the app (if desired) and tap "Add".
  4. The PWA should now appear on your home screen.

Other browsers on iOS

Browsers on iOS other than Safari (like Chrome) have limited PWA functionality. In addition to lacking Web Push Notifications (like Safari), PWA installation isn't supported.

If you use one of these browsers and want to add Nimbus to your home screen, you need to use Safari and follow the instructions above.

Firefox

To install a PWA on Firefox, follow these steps:

  1. Look for the install button or icon, usually located in the address bar or in a prompt that appears on the screen.
  2. Click on the install button or icon and follow the prompts to complete the installation.
  3. 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 PWA on Chromium based browsers, such as Google Chrome, Microsoft Edge, or Brave, follow these steps:

  1. Click on the menu button (three vertical dots) at the top right corner of the screen.
  2. Select "Install Nimbus as app" or "Install Nimbus to Home screen".
  3. Customize the name of the app (if desired) and click "Install" or "Add".
  4. The PWA should now appear on your device's home screen or in your app drawer.

FAQ

This FAQ is related to the PWA application for Nimbus. If you can't find the answer to your problem here, file an issue on Nimbus's repository in GitHub.

Permission denied: enable notifications in your browser

Before you enable push notifications in your browser, you need to enable notifications. Nimbus instructs the browser to show a notification permission prompt.

If you can't see the notification permission prompt, you need to remove push notification subscriptions. Check the previous section for information.

Your browser supports Web Push Notifications, but does not seem to implement the VAPID protocol.

If you receive this error, it means that either:

  1. Your browser doesn't support the VAPID protocol.
  2. Something is preventing the VAPID protocol from working in your browser.

The following browsers support the VAPID protocol:

  • Chrome
  • Brave
  • Edge
  • Safari
  • Firefox
  • Vivaldi
In Brave Browser, you need to allow "Use Google Services for Push Messaging" in "Settings" > "Privacy and security".

The VAPID protocol requires the clock to be set correctly on your computer or device, since this is used for certificate checks. Check that your clock is set to the correct date, time and timezone. After setting it correctly, restart your browser and try again.

If you still receive this issue after verifying your timezone settings, it means your browser doesn't support the VAPID protocol and you won't be able to receive push notifications.

Install Nimbus button not working

Most browsers enable applications to provide a custom PWA installation prompt. Some browsers, such as Arc browser, don't enable this. These issues can't be fixed by Nimbus. Check the browser's documentation for PWA installation instructions.

PWA Configuration in Nimbus project

By default, Nimbus enables PWA integration. You can be disable this by setting VITE_DEV_PWA to false in your .env file.

You can find the configuration options for the PWA in config/pwa.ts module.

PWA Web Manifest

Currently, there is no support for web manifest internationalization or theme color in any browser. We're using a custom module to generate web manifests for theme color and language variants.

Nimbus generates two web manifests per locale: one for light theme and one for dark theme.

You can check web manifest generation in modules/pwa/i18n.ts module.

PWA Icons

Nimbus's favicon and PWA icons are generated from Nimbus's SVG Logo via a custom script, using the sharp and sharp-ico libraries:

  • favicon.ico: transparent 64x64 32-bits icon
  • pwa-64x64.png: transparent 64x64 8-bits icon (optimized from 32-bits color)
  • pwa-192x192.png: transparent 192x192 8-bits icon (optimized from 32-bits color)
  • pwa-512x512.png: transparent 512x512 8-bits icon (optimized from 32-bit color)
  • maskable-icon.png: white background 512x512 8-bits icon (optimized from 32-bits color)
  • apple-touch-icon.png: white background 180x180 8-bits icon (optimized from 32-bits color)

PWA UI Components

Nimbus provides a set of UI components that allow you to customize the PWA installation prompt on browsers with beforeinstallprompt support.

You can find the PWA installation prompt in the PwaInstallPrompt component: this is shown on the right aside on wide screens, or at top on small screens.

Nimbus uses prompt for update strategy, so the PWA prompt for update will be shown only if there is a new version of Nimbus available.

  • On small screens, the PWA prompt for update is shown as a button on the head. You can find it in PwaBadge component.
  • On wide screens, the PWA prompt for update is shown as a prompt on the right aside. You can find it in PwaPrompt component.

PWA prompt for update takes preference over the PWA installation prompt. If there is a new version of Nimbus available, the PWA prompt for update will be shown instead of the PWA installation prompt.

The UI components mentioned here don't contain any logic. They all use the logic provided by the PWA plugin.

Service Worker

You can find Nimbus custom service worker in the service-worker folder, it provides:

Push Notifications Subscription Logic

Nimbus allows you to send push notifications to your users, you can find the logic for Web Push Notifications subscription in the composables/push-notifications folder.

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. You need to unregister the previous push subscription before registering a new one.

Debugging PWA in development

To debug the PWA in development, you need to run dev:pwa or dev:mocked:pwa script.

Running one of previous scripts starts 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 the 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 Nimbus.

Debugging PWA in mobile browsers

To debug the PWA service worker in your mobile browser, you 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.
  1. Connect your Android device to your computer using a USB cable.
  2. 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.
  1. 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.
  1. 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 redundant.
  1. 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".
Table of Contents