Upload files to "create-standalone-app-from-webapp"

2026-05-16 04:57:17 +02:00
parent 549375215f
commit 144e7cd63c
2 changed files with 296 additions and 0 deletions
--- a/create-standalone-app-from-webapp/setting-up-pwas.md
+++ b/create-standalone-app-from-webapp/setting-up-pwas.md
@@ -0,0 +1,296 @@
+# Setting up PWAs
+
+This document steps you through turning a WebApp into a standalone PWA (Progressive Web App). Run all steps from your home folder `/home/{your-username}`.
+
+> This document references KDE Plasma as that is what everything was testing in, however it should also work for other major Desktop Environments such as GNOME, XFCE, Cinnamon, etc.
+
+## 1. Install Google Chome with Flatpak
+
+*This step is only required if Google Chrome is not installed. If it is installed another way then uninstall it and install using Flatpak to ensure the latest PWA features and support.*
+
+`flatpak install flathub com.google.Chrome`
+
+> Run as root if you want Google Chrome to be install for all users
+
+## 2. Create required folders for PWAs
+
+*This step is only required when creating the first PWA.*
+
+```
+mkdir -p ~/.chrome-profiles
+mkdir -p ~/.local/bin
+mkdir -p ~/.local/share/applications
+mkdir -p ~/.local/share/desktop-directories
+mkdir -p ~/.local/share/icons/hicolor/16x16/apps
+mkdir -p ~/.local/share/icons/hicolor/32x32/apps
+mkdir -p ~/.local/share/icons/hicolor/48x48/apps
+mkdir -p ~/.local/share/icons/hicolor/128x128/apps
+mkdir -p ~/.local/share/icons/hicolor/256x256/apps
+```
+
+## 3. Give Google Chrome read and write access to required folders
+
+*This step is only required when creating the first PWA.*
+
+`flatpak override --user --filesystem=$HOME/.local/share/applications:create --filesystem=$HOME/.local/share/icons:create --filesystem=$HOME/.chrome-profiles:create com.google.Chrome`
+
+## 4. Create a Custom Submenu in KDE Plasma for the PWA.
+
+*This step is only required when you want a custom submenu for the PWA.*
+
+`nano {unique-name-for-subdirectory}.directory`
+
+Enter in the following text:
+
+```
+[Desktop Entry]
+Type=Directory
+Name={unique-name-for-subdirectory}
+Icon={unique-name-for-subdirectory-icon}
+```
+
+> {unique-name-for-subdirectory-icon} can only contain lowercase, digits and dashs (-) and must not have a file extension. KDE Plasma will load the correct size {unique-name-for-subdirectory-icon}.png file in `~/.local/share/icons/hicolor/...`.
+
+Press CTRL+X, then Y, then ENTER.
+
+## 5. Create a Custom Icon Set for the Custom Submenu in KDE Plasma
+
+*This step is only required when you carry out step 4.*
+
+Create a PNG image with transparent background at a resolution of 256px X 256px and save it to `~/.local/share/icons/hicolor/256x256/apps/{unique-name-for-subdirectory-icon}.png`.
+
+Resize the PNG image to 128px X 128px and save it to `~/.local/share/icons/hicolor/128x128/apps/{unique-name-for-subdirectory-icon}.png`.
+
+Resize the PNG image to 48px X 48px and save it to `~/.local/share/icons/hicolor/48x48/apps/{unique-name-for-subdirectory-icon}.png`.
+
+Resize the PNG image to 32px X 32px and save it to `~/.local/share/icons/hicolor/32x32/apps/{unique-name-for-subdirectory-icon}.png`.
+
+Resize the PNG image to 16px X 16px and save it to `~/.local/share/icons/hicolor/16x16/apps/{unique-name-for-subdirectory-icon}.png`.
+
+## 6. Create a folder for the PWA
+
+`mkdir -p ~/.chrome-profiles/{unique-name-for-pwa}`
+
+> {unique-name-for-pwa} can only contain lowercase, digits and dashes (-).
+
+## 7. Create Launch Script for the PWA
+
+`nano ~/.local/bin/{unique-name-for-pwa}`
+
+Enter the following text:
+
+```
+#!/bin/bash
+exec flatpak run com.google.Chrome \
+  --user-data-dir=$HOME/.chrome-profiles/{unique-name-for-pwa} \
+  --class={unique-name-for-pwa} \
+  --app={full-url-to-webapp}
+```
+
+Press CTRL+X, then Y, then ENTER.
+
+`chmod +x ~/.chrome-profiles/{unique-name-for-pwa}`
+
+## 7. Create Application Launcher for PWA
+
+`nano ~/.local/share/applications/{unique-name-for-pwa}.desktop`
+
+Enter the following text:
+
+```
+[Desktop Entry]
+Name={unique-title-for-pwa-as-it-is-to-appear-in-menu}
+Exec=/home/{your-username}/.local/bin/{unique-name-for-pwa}
+Icon={unique-name-for-pwa}
+Type=Application
+Categories={category};{category};
+StartupWMClass={unique-name-for-pwa}
+```
+
+Press CTRL+X, then Y, then ENTER.
+
+> {your-username} must be substituted with your actual login user name. If you are not sure then type `pwd` from your home folder and it is the string that follows the last slash (/).
+
+> {unique-name-for-pwa} for Icon must not contain a file extension. KDE Plasma will automatically load the correct size {unique-name-for-subdirectory-icon}.png file in `~/.local/share/icons/hicolor/...`.
+
+> For Categories you can define one or more category titles. These are used to place the PWA in the relevant submenus. If you are using a custom submenu then use a category name that matches {unique-name-for-subdirectory}. They are also used for easy search of the menu.
+
+### Main Standard Categories
+
+| Category | Meaning |
+| --- | --- |
+| AudioVideo | Multimedia Apps |
+| Audio | Audio-only Apps |
+| Video | Video-only Apps |
+| Development | Programming / Development |
+| Education | Educational Software |
+| Game | Games |
+| Graphics | Graphics / Image Editing |
+| Network | Internet / Network |
+| Office | Office / Productivity |
+| Science | Scientific Apps |
+| Settings | Settings / Configuration |
+| System | System tools |
+| Utility | General utilities |
+
+### Office Related Categories
+
+- Calendar
+- ContactManagement
+- Database
+- Dictionary
+- Email
+- Finance
+- FlowChart
+- PDA
+- ProjectManagement
+- Presentation
+- Spreadsheet
+- WordProcessor
+
+### Network Related Categories
+
+- Chat
+- Dialup
+- Email
+- Feed
+- FileTransfer
+- HamRadio
+- InstantMessaging
+- IRCClient
+- News
+- P2P
+- RemoteAccess
+- Telephony
+- VideoConference
+- WebBrowser
+
+### Development Related Categories
+
+- Building
+- Debugger
+- IDE
+- GUIDesigner
+- Profiling
+- RevisionControl
+- Translation
+
+### Graphics Related Categories
+
+- 2DGraphics
+- 3DGraphics
+- OCR
+- Photography
+- Publishing
+- RasterGraphics
+- Scanning
+- VectorGraphics
+- Viewer
+
+### Audio/Video Related Categories
+
+- Midi
+- Mixer
+- Music
+- Player
+- Recorder
+- Sequencer
+- TV
+- Tuner
+- VideoEditing
+
+### System Related Categories
+
+- Emulator
+- FileManager
+- Filesystem
+- Monitor
+- PackageManager
+- Security
+- TerminalEmulator
+
+## 8. Create a Custom Icon Set for the PWA
+
+Create a PNG image with transparent background at a resolution of 256px X 256px and save it to `~/.local/share/icons/hicolor/256x256/apps/{unique-name-for-pwa}.png`.
+
+Resize the PNG image to 128px X 128px and save it to `~/.local/share/icons/hicolor/128x128/apps/{unique-name-for-pwa}.png`.
+
+Resize the PNG image to 48px X 48px and save it to `~/.local/share/icons/hicolor/48x48/apps/{unique-name-for-pwa}.png`.
+
+Resize the PNG image to 32px X 32px and save it to `~/.local/share/icons/hicolor/32x32/apps/{unique-name-for-pwa}.png`.
+
+Resize the PNG image to 16px X 16px and save it to `~/.local/share/icons/hicolor/16x16/apps/{unique-name-for-pwa}.png`.
+
+## 9. Reload KDE Plasma
+
+> This step only applies to KDE Plasma. If you are using a different Desktop Environment then you will need to Google it or simply log out and log back in. Failing that, restart your system.
+
+`kbuildsycoca6 && kquitapp6 plasmashell && kstart plasmashell`
+
+Now you can launch your PWA from the Menu.
+
+> If the WebApp has a different URL for signing in than what you use for launching then close the PWA if it is running and type `flatpak run com.google.Chrome --user-data-dir=$HOME/.chrome-profiles/{unique-name-for-pwa} {full-url-for-signing-in}` then sign in, close Google Chrome and relaunch the PWA.
+
+## 10. Set PWA Permissions
+
+Google Chrome will not always give you an option to allow permissions for things like Notifications, Webcam, Microphone, etc, when running a PWA. To by pass this you can follow this step.
+
+*First close the PWA if it is running.*
+
+`flatpak run com.google.Chrome --user-data-dir=$HOME/.chrome-profiles/{unique-name-for-pwa} {full-url-to-webapp}`
+
+When Google Chrome has loaded the Web App, to the left of the URL you will find a small icon that looks like two lines with two small circles, orientated opposite to each other. Click the icon and then click Site Settings. A new page will open. Scroll down to Permissions and set your permissions are you require.
+
+Here are some common examples:
+
+- **Camera = Allow** - This will allow the PWA to use your WebCam
+- **Microphone = Allow** - This will allow the PWA to use your Microphone
+- **Notifications = Allow** - This will allow the PWA to provide Notifications to your Desktop Environment (Good for Popups in WebApps like Outlook and WhatsApp Web)
+- **Javascript = Allow** - This will allow the PWA to run Javascript (Most PWAs will need this)
+- **Images = Allow** - This will allow the PWA to download and display images
+- **Pop-ups And Redirects = Allow** - This will allow the PWA to open Pop-ups and Redirects (Good for Links in WebApps like Outlook and WhatsApp Web)
+- **Background Sync = Allow** - This will allow the PWA to continue running in the backgound if the window is not currently active
+- **Sound = Allow** - This will allow the PWA to play sounds (Good for Alerts and Notification Sounds)
+- **Automatic Downloads = Allow** - This will allow the PWA to Download Automatically without asking first (Downloads should be saved to `~/Downloads/`)
+- **Clipboard = Allow** - This will allow the PWA to use your Clipboard
+
+When you have set your permissions, close Google Chrome and you can relaunch the PWA with the chosen permissions set.
+
+## BONUS - An Example PWA for WhatsApp Web
+
+You can download the zip file included in the folder of this document and unzip it to your home folder. But you will need to complete steps 1 to 3 first.
+
+**IMPORTANT STEP AFTER UNZIPPING**
+
+Edit the file `~/.local/share/applications/whatsapp.desktop` and replace the text {your-username} with your actual login user name. If you are not sure then type `pwd` from your home folder and it is the string that follows the last slash (/). 
+
+Then run `chmod +x ~/.local/bin/whatsapp`.
+
+Then reload KDE Plasma.
+
+> This step only applies to KDE Plasma. If you are using a different Desktop Environment then you will need to Google it or simply log out and log back in. Failing that, restart your system.
+
+`kbuildsycoca6 && kquitapp6 plasmashell && kstart plasmashell`
+
+Now you can launch Whatsapp from the Menu.
+
+Please note that no permissions will be set for WhatsApp by default. You can set them by first closing WhatsApp and then running this command:
+
+`flatpak run com.google.Chrome --user-data-dir=$HOME/.chrome-profiles/whatsapp https://web.whatsapp.com`
+
+Refer to step 10 (Set PWA Permissions) for further information.
+
+## DONATIONS
+
+If you found this guide useful then please consider making a small donation. Even though my scripts are open source and free to use, I still need to eat. And the occasional bottle of wine also goes down well.
+
+- $5 buys me a cup of coffee
+- $10 buys me a nice burger
+- $20 buys me a bottle of wine
+- Anything above that will be awesome as well.
+
+You can send me a donation via Paypal https://www.paypal.com/paypalme/thisiszeev
+
+Drop me a message on Reddit if you do make a donation. u/thisiszeev
+
+Support is only offered freely to those who donate $20 or more.