https://github.com/tmtek/preact-pwa-install
A library for adding PWA install prompts to Preact apps.
https://github.com/tmtek/preact-pwa-install
Last synced: 4 months ago
JSON representation
A library for adding PWA install prompts to Preact apps.
- Host: GitHub
- URL: https://github.com/tmtek/preact-pwa-install
- Owner: tmtek
- License: bsd-3-clause
- Created: 2019-03-30T12:55:48.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T18:55:27.000Z (over 3 years ago)
- Last Synced: 2025-08-23T08:29:38.729Z (11 months ago)
- Language: JavaScript
- Size: 1.42 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# preact-pwa-install
Prompt users to install your Preact Progessive Web Application(PWA) as a native application on desktop or mobile. [Details on requirements can be found here](https://developers.google.com/web/fundamentals/app-install-banners/).
#### Preact 8:
```
npm i preact-pwa-install
```
#### Preact X:
```
npm i preact-pwa-install@preactx
```
#### Installation Example Apps
* [Preact 8 PWA](https://nifty-allen-800eb0.netlify.com/) ([Source](https://github.com/tmtek/pwa-install-test))
* Preact X PWA([Source](https://github.com/tmtek/pwa-install-testX))
### Capturing the browser prompt
Before getting into the specifics of the tools on offer in this package, it is important to understand that the prompts the the browser hands off to this library can be given very early in the lifecycle of your application.
It is recommended that you call the following function as early as possible in the lifetime of your app:
```javascript
import { awaitInstallPrompt } from 'preact-pwa-install';
/*
The following function call will start listening
for prompts from the browser. Prompts will be retained
so that any calls in the future may utilize them.
*/
cancel = awaitInstallPrompt();
//cancel() //stops listening to the browser for prompts.
```
## Preact X Hook
### useInstaller
The `useInstaller` hook is available for you to use in your components:
```javascript
import { h } from 'preact';
import { useInstaller } from 'preact-pwa-install';
export default function InstallButton(){
const { installPrompt, isStandalone } = useInstaller();
return installPrompt && Install as PWA
|| isStandalone && 'PWA is installed!';
}
```
## Preact 8 HOC
### installer
Any component that the `installer` HOC wraps will be provided with the following props:
```javascript
import { h } from 'preact';
import { installer } from 'preact-pwa-install';
function InstallButton({ isStandalone, installPrompt }){
return installPrompt && Install as PWA
|| isStandalone && 'PWA is installed!';
}
export default installer()(InstallButton);
```
## Functions
### isStandalone
You may import `isStandalone` to check to see if you are running as a PWA at any time:
```javascript
import { isStandalone } from 'preact-pwa-install';
let isStandalone = isStandalone(); //true/false
```
### awaitInstallPrompt
The `awaitInstallPrompt` function allows you to listen to the browser for permission to prompt the user to install your app. Permission comes in the form of a `prompt` function you may call at any time in the future:
```javascript
import { awaitInstallPrompt } from 'preact-pwa-install';
let cancel = awaitInstallPrompt(prompt =>
prompt().then(success => console.log(
success && 'Successfully installed app as PWA.'
|| 'User abandoned install.'
))
//On a successful install, listening will be stopped automatically.
);
/*
cancel() at any time in the future to stop listening for prompts.
*/
```
This function may be called with no arguments, and doing so will just start listening to the browser for prompts. Prompts that are receieved are retained so that additional calls to `awaitInstallPrompt` will be invoked automatically with the retained prompt.
## reset
The reset function exists to be able to clear any retained prompts and to remove all window listeners used to capture prompts from the browser.
This function primarily for the purposes of testing. It is recommended that you use cancel functions returned from your `awaitInstallPrompt()` calls instead of turning to `reset()`.