Skip to content

feat: Guide users to install PWA - #1380

Open
Pecacheu wants to merge 3 commits into
mainfrom
pwainstall
Open

Pecacheu wants to merge 3 commits into
mainfrom
pwainstall

Conversation

@Pecacheu

@Pecacheu Pecacheu commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

This is a rebase of #1077 on latest main + dropping the message.po files, since @Misofist didn't get around to it for a while. I also dropped the PWA SW update change, that should probably be in its own PR since it requires its own testing to ensure it actually works.

On mobile browsers, the "Install" menu appears in settings.

On browsers with support for beforeinstallprompt, an easy install button is present.

Pressing it displays the native browser install prompt.

--> -->

On a tablet (iPad Mini sized):

If you decline the installation prompt:

On older mobile browsers where automatic install isn't supported, only the manual directions are shown. (And yes the different capitalization is intentional, that's exactly how it's displayed on iOS vs Android, little cursed fun fact for you lmao)

And once PWA is installed, the option disappears. It also only appears on mobile devices, since there is little point to installing the PWA on Desktop.

Original PR description below

This builds on the work done by Pecacheu in #1024, but completely reworks the UX.

No modal window is shown. Instead, a new "Install" option has been added to the Settings menu.

On browsers that support the beforeinstallprompt event, this page contains a button to install the PWA. Clicking this button starts the PWA install experience. This also gracefully handles the case where the user declines the installation. For browsers which do not support the beforeinstallprompt event, manual installation instructions are shown. The install button is hidden within the PWA itself. The install button also only appears on mobile browsers, since currently on desktop I think there is little point in installing the PWA.

I also updated the way we use Vite PWA to follow their best practices for SW updates: https://vite-pwa-org.netlify.app/guide/periodic-sw-updates.html#handling-edge-cases

@Pecacheu
Pecacheu requested review from a team as code owners July 24, 2026 14:15
@Dadadah

Dadadah commented Jul 24, 2026

Copy link
Copy Markdown
Member

can you update the screenshots to this pr to feature the latest version (with the mobile branch) to allow ui/ux review

@Pecacheu

Copy link
Copy Markdown
Contributor Author

@Dadadah Screenshots added!

@Pecacheu
Pecacheu force-pushed the pwainstall branch 4 times, most recently from b9fd40d to 5b617b5 Compare July 28, 2026 01:40
@Pecacheu
Pecacheu force-pushed the pwainstall branch 2 times, most recently from 182a149 to 688ac02 Compare July 31, 2026 16:01

@Dadadah Dadadah left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need to include installation instructions on this page - what if we instead put up a support article for installation and just linked to that? I feel that might match the behavior of similar systems better. This may be a UI/UX issue.

Is it really worth importing vite-plugin-html-minifier? You're talking a savings of like a few bytes as it won't even minifiy the event names, I don't think we need to import 90 packages for this.

Comment thread packages/client/components/app/interface/settings/InstallInstructions.tsx Outdated
Comment thread packages/client/components/app/interface/settings/InstallInstructions.tsx Outdated
Comment thread packages/client/fontpreload.plugin.ts
@Pecacheu

Pecacheu commented Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

I'm not sure we need to include installation instructions on this page - what if we instead put up a support article for installation and just linked to that? I feel that might match the behavior of similar systems better. This may be a UI/UX issue.

Well someone would need to create that but I think either approach would be fine, as long as it's easy to understand like the writeup in this PR is.

Hmm then again, might be harder for the user to follow it given they'd be doing this on a phone specifically, so avoiding making them go open up an external link on their little phone browser just to read some directions might make more sense vs on PC.

Is it really worth importing vite-plugin-html-minifier? You're talking a savings of like a few bytes as it won't even minifiy the event names, I don't think we need to import 90 packages for this.

That is a good point lol, didn't think about how heavy that dep might be compared to the small savings given our single HTML file. On the plus side it seemed to add no precipitable change to build time.

@Pecacheu
Pecacheu force-pushed the pwainstall branch 2 times, most recently from 63063bd to 8d15c4f Compare August 7, 2026 23:46
Comment thread packages/client/components/app/interface/settings/InstallInstructions.tsx Outdated
Comment thread packages/client/components/app/interface/settings/InstallInstructions.tsx Outdated
@Dadadah

Dadadah commented Aug 10, 2026

Copy link
Copy Markdown
Member

Sorry i didn't catch these earlier but I think these features I'm mentioning are new anyway. Once you address these two I think we can get this to UI review.

Btw were you going to remove the .html file minification?

@Pecacheu

Copy link
Copy Markdown
Contributor Author

Btw were you going to remove the .html file minification?

Idk, I don't like the idea of having unminified code in production but I guess it's not doing too much harm when it's only one file that's only ~1 KB

@Pecacheu
Pecacheu force-pushed the pwainstall branch 3 times, most recently from bf04720 to 920db47 Compare August 10, 2026 15:26
@Pecacheu

Copy link
Copy Markdown
Contributor Author

Ok I at least disabled formatting of <script> tag in HTML so that we could use the minified version of the JS inside the HTML, this saves 200 bytes and more importantly, allows me to sleep at night

Misofist and others added 3 commits August 10, 2026 11:35
fix: Make dialog less wordy
refactor: Simplify Install page styles
fix: Move event code to inline script to improve detection reliability
undo: Drop unrelated serviceWorkerInterface change
fix: Add note about minify
fix: Move isPWA to Device context
fix: Enable HTML minify in prod
fix: Update lockfile
fix: Use Symbol, use gap-lg for padding

Signed-off-by: Pecacheu <3608878+Pecacheu@users.noreply.github.com>

Replace PWA modal with button in settings menu
This also aligns the way we use vite-pwa-plugin with modern best practices
Skip unnecessary destructuring
Add refresh button if user declined PWA installation

Signed-off-by: Misofist <misofist@heavendivided.net>
Signed-off-by: Pecacheu <3608878+Pecacheu@users.noreply.github.com>
Signed-off-by: Pecacheu <3608878+Pecacheu@users.noreply.github.com>
@Pecacheu Pecacheu added the ux review This needs UX review label Aug 10, 2026
PoBruno added a commit to PoBruno/stoat-for-web that referenced this pull request Aug 24, 2026
The download page offers an installer for Windows and a package for
Debian, neither of which means anything on a phone, and it was the only
thing the app said about installing itself. Someone reading on a phone had
no way to get past the browser tab.

Settings now carries instructions for installing the web app, shown only
on a phone and only while it has not been installed. The download entry
gets the opposite condition for the same reason.

From stoatchat#1380, minus two things it carried that have nothing
to do with installing: an editor setting, and the removal of the ordering
on the font preload plugin.

The snippet that captures the install event stays in the HTML, since the
browser fires it before the app has loaded and there is nothing listening
yet, but it arrived minified into one line and is written out here.

Signed-off-by: pobruno <brunoshy@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ux review This needs UX review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants