to-pwa
v1.0.4
Published
Turn any web page into a Progressive Web App by simply importing a script.
Downloads
13
Readme
Here's the content rewritten in README.md format for your to-pwa library:
# to-pwa
`to-pwa` is a lightweight JavaScript utility that helps you integrate Progressive Web App (PWA) functionality into your website or web app. This library registers the service worker, adds the manifest, and shows a custom install prompt for users to install the web app onto their devices.
## Features
- **Service Worker Registration**: Automatically registers your service worker for offline capabilities.
- **Manifest Integration**: Injects the necessary PWA manifest into the HTML document.
- **Custom Install Prompt**: Displays a custom install prompt to encourage users to install your app.
- **Theme Color Setup**: Adds a theme color meta tag for customizing the look and feel.
## Installation
To install the `to-pwa` library, you can use npm:
```bash
npm install to-pwaOr include it directly in your project:
<script src="path-to-to-pwa.js"></script>Usage
To integrate to-pwa into your project, pass the required options (service worker path, manifest path, and icon path) to the toPWA function.
Example
import toPWA from 'to-pwa';
toPWA({
swPath: '/sw.js', // Path to your service worker file
manifestPath: '/manifest.json', // Path to your manifest file
iconPath: '/images/icon.png', // Path to your app icon
themeColor: '#2196f3' // Optional: Custom theme color
});Options
swPath(required): Path to your service worker file.manifestPath(required): Path to your PWA manifest file.iconPath(required): Path to your app icon.themeColor(optional): Custom theme color for your PWA (default:#ffffff).
Key Features
1. Service Worker Registration
to-pwa automatically registers your service worker to enable offline capabilities:
navigator.serviceWorker
.register(options.swPath)
.then((reg) => console.log('Service Worker registered:', reg))
.catch((err) => console.error('Service Worker registration failed:', err));2. Manifest File Injection
The library injects your manifest file into the HTML <head> element to define your app's metadata as a PWA:
const manifestEl = document.createElement('link');
manifestEl.rel = 'manifest';
manifestEl.href = options.manifestPath;
document.head.appendChild(manifestEl);3. Custom Install Prompt
to-pwa shows a custom install prompt when a user is eligible to install your app as a PWA:
const installPopup = document.createElement('div');
installPopup.id = 'install-popup';
installPopup.innerHTML = `
<p>Install this app to your home screen for a better experience!</p>
<button id="install-button">Install</button>
<button id="close-popup">Close</button>
`;
document.body.appendChild(installPopup);4. Theme Color Meta Tag
The library adds a theme-color meta tag to the HTML document for PWA appearance customization:
const themeColorMeta = document.createElement('meta');
themeColorMeta.name = 'theme-color';
themeColorMeta.content = options.themeColor || '#ffffff';
document.head.appendChild(themeColorMeta);Handling Install Events
You can handle the beforeinstallprompt and appinstalled events to customize the installation flow for your users:
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferredPrompt = e;
// Show custom install popup
});
window.addEventListener('appinstalled', () => {
console.log('PWA was successfully installed.');
});Browser Compatibility
to-pwa works in all modern browsers that support PWAs, including:
- Google Chrome
- Mozilla Firefox
- Microsoft Edge
- Safari (limited support)
Contributing
Contributions are welcome! If you find a bug or have an improvement suggestion, feel free to submit an issue or a pull request to the repository.
License
This project is licensed under the MIT License.
Keywords
- PWA
- Progressive Web App
- JavaScript PWA library
- Service Worker
- Manifest
- Web App Install
- Offline Web App
- Custom Install Prompt
- Theme Color
- Web Application
This version of the `README.md` is structured to ensure clear instructions and proper keyword optimization for search engines and npm rankings.