Frequently Asked Questions¶

From MDN Web Docs:

A progressive web app (PWA) is an app that's built using web platform technologies, but that provides a user experience like that of a platform-specific app.

Like a website, a PWA can run on multiple platforms and devices from a single codebase. Like a platform-specific app, it can be installed on the device, can operate while offline and in the background, and can integrate with the device and with other installed apps.

Although Firefox supports many of Progressive Web App APIs, it does not support functionality to install them as a standalone system app with an app-like experience. This functionality is often also known as a Site Specific Browser (SSB).

This project creates a custom modified Firefox runtime to allow websites to be installed as standalone apps and provides a console tool and browser extension to install, manage and use them. For more details about how it achieves that, you can check out the how it works page.

Most Chromium-based browsers have built-in support for PWAs/SSBs, which makes the initial setup easier. In comparison, this project is made as a Firefox extension and an additional native program, which can make the initial setup a bit more complicated, but also allows additional features that Chromium-based browsers do not support.

Unique features that PWAsForFirefox supports include:

• Support for separate profiles: Although it might sometimes be more convenient to use the same profile for PWAs and main browsing (as this is done on Chromium), using separate profiles allows you to do more things that aren't possible on Chromium. This includes extra customization or using multiple accounts for the same web app.

• More customization options: This project supports additional configuration abilities that Chromium-based browsers do not. Customization options that the project supports include allowing the customization of the browser toolbar with widgets, different browser settings for different web apps, installing additional addons, etc. In addition, the behavior can also be highly customized with the available settings.

• Better integration with the desktop: Web apps installed with this project can provide better visual and functional integration than some Chromium-based browsers. Additionally, the ability to customize the look using CSS allows web apps to visually match any platform.

• Browser diversity: Most web app runtimes are currently based on Blink/WebKit, which limits the web diversity. Being based on Firefox, this project provides an alternative runtime and promotes the browser diversity and healthier ecosystem of web platforms.

• And more!

You can read the installation page for the installation instructions. Instructions for installing the native program are also displayed directly in the extension setup wizard. For usage instructions, you can check the user guide.

The project provides a portable installer (.paf.exe), which can be downloaded from the GitHub Releases page. It is recommended to install it through the PortableApps.com Platform for additional integration with its app menu.

Before being able to use the browser extension with the portable version, you will have to start PWAsForFirefox Portable. This will launch a small background program that makes sure the browser is connected to the portable version. This program can be closed from the taskbar tray icon when you do not need it.

You can customize install locations for most directories using build-time environment variables. However, this will only change where the program expects the files to be, and you will need to manually copy the files to the correct locations. You will also need to manually edit the native app manifest with the correct path to the connector.

Descriptions of each directory, their default locations, and a list of environment variables to change them are available on the directories page. If you want to specify a location in the home directory, start the environment variable with ~/, and it will be expanded to the user home directory at the run-time.

If you want to install the runtime to a global directory, you can manually install the runtime to a runtime directory in the system data directory and remove any existing runtime in the user data directory. You also need to make sure that the directory is writeable by all users to make the patching work.

Changing the runtime directory to other locations (unrelated to user or system data directories) requires editing the source code.

The extension should work with most actively-developed Firefox-based browsers or forks. However, some of them have different search locations for native messaging manifests, so the extension might not detect the native program. You will need to check the documentation of your browser for specific manifest locations and copy the manifest to the correct one.

ln -s ~/.mozilla/native-messaging-hosts ~/.librewolf/native-messaging-hosts
sudo ln -s /usr/lib/mozilla/native-messaging-hosts /usr/lib/librewolf/native-messaging-hosts

sudo mkdir -p /usr/lib/librewolf/native-messaging-hosts
sudo ln -s /usr/lib/mozilla/native-messaging-hosts/firefoxpwa.json /usr/lib/librewolf/native-messaging-hosts/firefoxpwa.json

ln -s ~/Library/Application\ Support/Mozilla/NativeMessagingHosts ~/Library/Application\ Support/LibreWolf/NativeMessagingHosts
sudo ln -s /Library/Application\ Support/Mozilla/NativeMessagingHosts /Library/Application\ Support/LibreWolf/NativeMessagingHosts

sudo mkdir -p /Library/Application\ Support/LibreWolf/NativeMessagingHosts
sudo ln -s /Library/Application\ Support/Mozilla/NativeMessagingHosts/firefoxpwa.json /Library/Application\ Support/LibreWolf/NativeMessagingHosts/firefoxpwa.json

Instead of using the default runtime (normal Firefox), you can manually download an alternative Firefox version or Firefox fork (LibreWolf, IceCat, Waterfox, etc.). However, please keep in mind that compatibility with other or unofficial runtimes is not guaranteed.

To apply UserChrome modifications to the new runtime, you may need to patch profiles and runtime from the extension settings.

On compatible Linux distributions, it is possible to use FUSE OverlayFS to link your global Firefox installation with the PWAsForFirefox runtime. This removes the need to manage and store two separate Firefox installations, but requires an additional setup.

Detailed instructions are available in the GitHub gist.

The project aims to make installed web apps look native. However, due to a large number of Linux desktop environments and customization options, it's hard to detect them and provide the correct built-in compatibility styles with each of them. However, there are two ways how you can manually achieve a better visual integration with your theme.

One way of achieving the native titlebar is to disable client-side decorations (CSD) for installed web apps. This can be done on the Firefox customized page by unchecking the titlebar checkbox. However, this will cause a separate bar to appear, which might be undesirable, visually unappealing and screen-inefficient.

A better solution is to manually apply custom CSS styling to customize the titlebar appearance. See how to apply custom CSS to web apps and include CSS for your platform that is provided below (you can also customize it if you want).

@-moz-document url('chrome://browser/content/browser.xhtml') {
  /* Horizontally center the title element */
  .site-info {
    justify-content: center !important;
  }

  /* Remove the icon element */
  .tab-icon-image {
    display: none !important;
  }

  /* Remove space between hamburger menu and window controls */
  .titlebar-spacer[type="post-tabs"] {
    width: 0 !important;
  }
}

@-moz-document url('chrome://browser/content/browser.xhtml') {
  /* Horizontally center the title element */
  .site-info > .tab-label-container {
    position: relative;
    margin-left: auto;
    margin-right: auto;
    left: 9rem;
  }
}

On Windows, it is possible to make the web app titlebar use the system accent color for active windows. This can be done by applying the following custom CSS:

@-moz-document url('chrome://browser/content/browser.xhtml') {
  #navigator-toolbox:not(:-moz-window-inactive),
  #scrollbutton-up:not(:hover):not(:active):not(:-moz-window-inactive),
  #scrollbutton-down:not(:hover):not(:active):not(:-moz-window-inactive),
  .tabbrowser-tab:not(:-moz-window-inactive) {
    background: AccentColor !important;
    color: AccentColorText !important;
    fill: AccentColorText !important;
  }

  #firefox-view-button[open] > .toolbarbutton-icon,
  .tab-background:is([selected], [multiselected]) {
    background-color: color-mix(in srgb, currentColor 18%, transparent) !important;
    background-image: none !important;
  }
}

You also need to disable the "Allow web apps to override a theme (titlebar) color" option in the app browser settings to prevent conflicts with the applied styles.

The runtime supports loading custom CSS (UserChromeCSS) in the same way as normal Firefox. For more details and resources about custom CSS, you can check the UserChromeCSS website.

To load custom CSS into the web app profile:

1. Locate your web app profile inside the profiles directory.
2. Inside the profile directory, create a chrome directory (if it does not exist yet).
3. Inside the chrome directory, create a userChrome.css file (if it does not exist yet).
4. Copy your CSS into the userChrome.css file.
5. Enable toolkit.legacyUserProfileCustomizations.stylesheets inside about:config.
6. Relaunch the web app.

If you want to apply CSS to multiple profiles, using profile templates can make this easier.

For advanced modifications, it is possible to load custom JS into the runtime using UserChromeJS (Autoconfig Startup Scripting).

To load custom JS into the web app profile:

1. Locate your web app profile inside the profiles directory.
2. Inside the profile directory, create a chrome directory (if it does not exist yet).
3. Inside the chrome directory, create a user directory (if it does not exist yet).
4. Inside the user directory, create a boot.jsm or boot.sys.mjs file (if it does not exist yet).
5. Copy your JS into the correct file (depending on the module format).
6. Relaunch the web app.

If you want to apply JS to multiple profiles, using profile templates can make this easier.

You can open the built-in addon manager using a standard keyboard shortcut or the app menu. You can also navigate to the addon store by opening the URL input (by pressing F6, Ctrl+L or Alt+D) and entering addons.mozilla.org.

You can access about:config (or any other URL) by opening the URL input (by pressing F6, Ctrl+L or Alt+D) and entering about:config.

It is possible to create a shortcut to the web app and add it to your desktop or other directory.

To back up installed web apps or transfer them to another computer, you can copy the config.json file and the profiles directory inside the user data directory.

After restoring the data, you need to run the "Update web apps" option from the extension settings to register your web apps to the operating system.

If you are building a development extension build yourself, the auto-reloading feature may prevent the extension from running on certain websites. To be able to install such websites, you either need to build a production build or use a pre-built extension.

Some Mozilla websites block extension content scripts for security reasons. You cannot install that sites using the extension. However, you may be able to install them manually using the command-line program.

Some websites cannot be installed with the manifest enabled because their manifests are invalid or do not follow the specifications properly. To install such websites, you can try disabling the use of manifest for determining the app properties. We maintain a list of those websites.

If the website is not a valid PWA, the page action (in the address bar) will not appear by default. However, you can install such websites from the main extension/browser action (the same place where all installed web apps are listed). This way of installing sites does not require PWA manifest, so it should work with basically any website.

Otherwise, you can check the troubleshooting tasks and create a new issue if needed.

When creating a profile (or installing a web app into a new profile) with template, you may receive error about non-existing files or directories or insufficient permissions. This might happen because you copied the directory to a template while that profile was running, which caused lock files to be copied along. It is recommended to close the profile before you copy it as a template to prevent such problems.

In case creating a profile failed because of supposedly non-existing files or directories, you may be able to fix this issue by removing a file named "lock" inside the template.

In case creating a profile failed because of insufficient permissions, make sure to apply the correct permission to all files and directories inside the template directory.

If the app browser looks like a normal Firefox, with tabs and the address bar displayed, this might be caused by your settings. Check if show browser tabs and enable using multi-tabbed web apps is enabled or display the address bar is set to always in the app browser settings. Disabling those options might fix your issue.

If the relevant settings are disabled but the app browser still appears like a normal Firefox, this has been caused by missing patches. You can run patch profiles and runtime from the extension settings to re-apply them.

Due to a known issue, when using fractional display scaling on Linux, the extension popup might be truncated. In this case, you might not be able to fully see all UI elements, notably the web app installation button.

A possible workaround is to use the Tab key to select the button and press Enter to execute it, or to temporarily disable fractional scaling when installing web apps.

If you are using Firefox Snap (default on Ubuntu)

Recent Firefox Snap versions on Ubuntu support native messaging. First, make sure that you are using recent enough Firefox and Ubuntu version.

When the extension first tries to access the native connector, a permission popup which you need to accept should appear. If the popup didn't appear, or you denied the permission, you need to manually allow it via the command line:

flatpak permission-set webextensions firefoxpwa snap.firefox yes

For this command to work, you will need Flatpak installed. After you ran the command and confirmed that the extension detected the native connector, you can remove Flatpak.

If you are using Firefox Flatpak

Flatpak does not support native messaging yet, but they are working on adding support for it. You can follow the xdg-desktop-portal issue for progress.

If you want to use PWAsForFirefox, you will need to use Firefox from your distribution's repository or Mozilla's website instead. Other workarounds may exist, but they are not officially supported.

If you are using Firefox from PPA or distribution's repository

Firefox distributed with some distributions can have bugs that break native messaging. Such bugs should be reported to the maintainers of that repository. You can instead use Firefox downloaded directly from Mozilla's website.

Because of a known problem, the installer might not detect an existing PWAsForFirefox installation and instead install a new version along the existing one.

This problem most often happens if you have initially installed PWAsForFirefox to a per-user location, but kept the default installation options when installing updates, which installed a newer version separately to a global directory.

This might cause the extension to detect and use a wrong/old native connector, which might not contain all the latest features and fixes.

To fix this problem:

1. Uninstall any existing PWAsForFirefox versions from the Windows Settings.

2. Remove directories C:\Program Files\FirefoxPWA and %LOCALAPPDATA%\Programs\FirefoxPWA, if they exist. If you have previously chosen a different installation directory, make sure to also remove it.

3. Remove registry keys HKLM\Software\filips\FirefoxPWA and HKCU\Software\filips\FirefoxPWA, if they exist.

4. Remove registry keys HKLM\Software\Mozilla\NativeMessagingHosts\firefoxpwa and HKCU\Software\Mozilla\NativeMessagingHosts\firefoxpwa, if they exist.

5. Reinstall PWAsForFirefox. To make it less likely that this problem occurs again, it is recommended to install PWAsForFirefox for all users and keep the default installation directory (C:\Program Files\FirefoxPWA). If you instead choose a different installation option, make sure to remember it and always select the same option and directory when installing updates.

6. Run the "Patch profiles and runtime" option from the extension settings.

Compiling the loader while installing a web app on macOS requires the Xcode Command Line Tools to be installed.

They should be automatically installed when using Homebrew. If they are not installed, you can install them by running the following command:

xcode-select --install

If the Xcode Command Line Tools are installed, but the web app installation still fails, you can try to remove them by running the following command and install them again:

sudo rm -rf /Library/Developer/CommandLineTools

Due to an unknown problem, trying to allow microphone or camera permissions may crash the web app on macOS.

As a workaround, it is possible to manually grant the required permissions to the app browser using the steps below. This needs to be done once for every profile where the microphone or camera access is required.

1. Create a web app into a new profile via the normal process.

2. Use Cmd+I to manually open the permissions window and select the "Permissions" tab.

3. Set "Microphone" and "Camera" to "Always Allow".

4. Click the 9-box grid in the upper right of the Google banner and then select Google Search. Search for "webcamtests" and then open the webcamtests.com website from the results.

5. Run the webcam test and the microphone test one after another.

6. A permission dialogs from macOS should appear for each test ("Do you want to allow NAME to access the Microphone?", "Do you want to allow NAME to access the Camera?".

7. Answer yes to both dialogs.

8. The microphone and camera should now work.