Registry / web-framework / pwa-helpers

pwa-helpers

JSON →
library0.9.1jsnpmunverified

pwa-helpers is a collection of small, focused helper methods and mixins designed to reduce boilerplate when building Progressive Web Apps. It offers utilities for common PWA features such as client-side routing, network connectivity detection, dynamic metadata updates for SEO and social sharing, and media query monitoring. The current stable version is 0.9.1, with recent updates including TypeScript support introduced in v0.9.0. This library is designed to be framework-agnostic, providing vanilla JavaScript functions that can integrate with any web application stack, differentiating itself by its minimalist approach rather than being a comprehensive framework.

npm install pwa-helpers
INSTALL
IMPORT
SIG · PWA-HELPERS
P
pwa-helpers
web-frameworkjavascriptv0.9.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

installRouter
import { installRouter } from 'pwa-helpers/router.js';
const { installRouter } = require('pwa-helpers/router');
This library is primarily ESM. Ensure your project and build tooling support ES module imports. The `.js` extension is crucial for browser compatibility and some Node.js environments.
updateMetadata
import { updateMetadata } from 'pwa-helpers/metadata.js';
import updateMetadata from 'pwa-helpers/metadata';
Symbols are named exports. Direct default imports are not provided by individual modules. The `.js` extension is important.
installOfflineWatcher
import { installOfflineWatcher } from 'pwa-helpers/network.js';
import { installOfflineWatcher } from 'pwa-helpers/network';
For ESM, always include the `.js` extension in the import path. This ensures proper resolution in browsers and some Node.js setups.

Demonstrates basic routing, dynamic metadata updates, and network connectivity detection using `pwa-helpers`. It includes both initial setup and simulated programmatic navigation, showing how to integrate these helpers into a client-side application structure, and handle network status changes.

import { installRouter } from 'pwa-helpers/router.js'; import { updateMetadata } from 'pwa-helpers/metadata.js'; import { installOfflineWatcher } from 'pwa-helpers/network.js'; // A dummy store and navigate action for the example const store = { dispatch: (action) => console.log('Dispatching action:', action) }; const navigate = (location) => ({ type: 'NAVIGATE', payload: location.pathname }); function handleNavigation(location, event = null) { console.log('Navigated to:', location.pathname); // Example of integrating with a Redux-like store store.dispatch(navigate(location)); // Update metadata based on the current route updateMetadata({ title: `My PWA - ${location.pathname.substring(1) || 'Home'}`, description: `Content for ${location.pathname}`, url: window.location.href }); if (event && event.type === 'click') { window.scrollTo(0, 0); console.log('Scrolled to top after click.'); } } // Install the router installRouter(handleNavigation); // Install the offline watcher installOfflineWatcher((offline) => { const message = offline ? 'You are currently OFFLINE' : 'You are currently ONLINE'; console.log(message); // Optionally update UI based on connectivity const statusElement = document.getElementById('network-status'); if (statusElement) statusElement.textContent = message; }); // Simulate a programmatic navigation setTimeout(() => { window.history.pushState({}, '', '/about'); handleNavigation(window.location); }, 2000); // Create a simple div for network status (if running in a browser environment) if (typeof document !== 'undefined') { const statusDiv = document.createElement('div'); statusDiv.id = 'network-status'; statusDiv.textContent = 'Checking network status...'; document.body.appendChild(statusDiv); }
Debug
Known issues
gotchapwa-helpers is designed as an ES Module (ESM) library. Attempting to use `require()` for imports in a CommonJS environment without proper transpilation or bundler configuration will lead to module resolution errors.
fix
Ensure your project uses `import` statements and is configured for ESM. If targeting Node.js, ensure `"type": "module"` is set in your `package.json` or use an appropriate bundler like Rollup or Webpack. For browser environments, use modern script tags with `type="module"` or a bundler.
affects: >=0.1.0
gotchaWhen programmatically changing the URL (e.g., in a single-page application), `installRouter`'s callback is not automatically triggered by `window.history.pushState` or `replaceState`. You must manually call the callback with `window.location` after modifying the history.
fix
After calling `window.history.pushState({}, '', '/new-route');`, explicitly invoke your `handleNavigation(window.location);` function (or whatever callback you passed to `installRouter`).
affects: >=0.1.0
gotchaThe `metadata.js` helper will only update fields for which values are explicitly provided. If a property like `image` or `description` is omitted from the object passed to `updateMetadata`, the corresponding Open Graph or Twitter card tag will not be set or updated, rather than cleared.
fix
Always provide all desired metadata fields, even if some are empty strings, if you want full control over the tags. To remove a tag, you might need to manually target and remove the corresponding meta element, as `pwa-helpers` doesn't provide a 'clear' mechanism for individual fields.
affects: >=0.1.0
gotchaThe TypeScript support introduced in `v0.9.0` adds type definitions. While this doesn't break JavaScript usage, projects with strict TypeScript configurations or specific build setups might need to ensure their `tsconfig.json` correctly includes or excludes declaration files if unexpected build issues arise.
fix
If encountering TypeScript-related build issues after upgrading, verify your `tsconfig.json` settings (e.g., `include`, `exclude`, `allowSyntheticDefaultImports`). Typically, modern TypeScript setups will consume these types without issues.
affects: >=0.9.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'call') at installRouter
Attempting to call `installRouter` (or other helpers) as a function when it was imported incorrectly, often due to a CommonJS `require()` in an ESM-only context or an incorrect named import.
fix
Ensure you are using named ES module imports: `import { installRouter } from 'pwa-helpers/router.js';`. Verify that your build setup correctly handles ES modules.
Error: Cannot find module 'pwa-helpers/router.js' or 'pwa-helpers/network.js'
Module resolution failure, often due to missing the `.js` extension in the import path, or incorrect pathing in a non-bundled environment.
fix
Always include the `.js` file extension in your `import` paths for `pwa-helpers` modules, e.g., `import { installRouter } from 'pwa-helpers/router.js';`. This is crucial for browser-native ESM and some Node.js module resolvers.
Upgrade
Version history
0.9.1latest on npm
Audit
Dependencies
axe-coreoptionalRequired for the `axeReport` utility for accessibility testing.
Agent activity
4 hits · last 30 days
node
4
Resources