{"id":15481,"library":"pwa-helpers","title":"PWA Helpers","description":"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.","status":"active","version":"0.9.1","language":"javascript","source_language":"en","source_url":"https://github.com/polymer/pwa-helpers","tags":["javascript"],"install":[{"cmd":"npm install pwa-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add pwa-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add pwa-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the `axeReport` utility for accessibility testing.","package":"axe-core","optional":true}],"imports":[{"note":"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.","wrong":"const { installRouter } = require('pwa-helpers/router');","symbol":"installRouter","correct":"import { installRouter } from 'pwa-helpers/router.js';"},{"note":"Symbols are named exports. Direct default imports are not provided by individual modules. The `.js` extension is important.","wrong":"import updateMetadata from 'pwa-helpers/metadata';","symbol":"updateMetadata","correct":"import { updateMetadata } from 'pwa-helpers/metadata.js';"},{"note":"For ESM, always include the `.js` extension in the import path. This ensures proper resolution in browsers and some Node.js setups.","wrong":"import { installOfflineWatcher } from 'pwa-helpers/network';","symbol":"installOfflineWatcher","correct":"import { installOfflineWatcher } from 'pwa-helpers/network.js';"}],"quickstart":{"code":"import { installRouter } from 'pwa-helpers/router.js';\nimport { updateMetadata } from 'pwa-helpers/metadata.js';\nimport { installOfflineWatcher } from 'pwa-helpers/network.js';\n\n// A dummy store and navigate action for the example\nconst store = {\n  dispatch: (action) => console.log('Dispatching action:', action)\n};\nconst navigate = (location) => ({ type: 'NAVIGATE', payload: location.pathname });\n\nfunction handleNavigation(location, event = null) {\n  console.log('Navigated to:', location.pathname);\n  // Example of integrating with a Redux-like store\n  store.dispatch(navigate(location));\n\n  // Update metadata based on the current route\n  updateMetadata({\n    title: `My PWA - ${location.pathname.substring(1) || 'Home'}`, \n    description: `Content for ${location.pathname}`, \n    url: window.location.href\n  });\n\n  if (event && event.type === 'click') {\n    window.scrollTo(0, 0);\n    console.log('Scrolled to top after click.');\n  }\n}\n\n// Install the router\ninstallRouter(handleNavigation);\n\n// Install the offline watcher\ninstallOfflineWatcher((offline) => {\n  const message = offline ? 'You are currently OFFLINE' : 'You are currently ONLINE';\n  console.log(message);\n  // Optionally update UI based on connectivity\n  const statusElement = document.getElementById('network-status');\n  if (statusElement) statusElement.textContent = message;\n});\n\n// Simulate a programmatic navigation\nsetTimeout(() => {\n  window.history.pushState({}, '', '/about');\n  handleNavigation(window.location);\n}, 2000);\n\n// Create a simple div for network status (if running in a browser environment)\nif (typeof document !== 'undefined') {\n  const statusDiv = document.createElement('div');\n  statusDiv.id = 'network-status';\n  statusDiv.textContent = 'Checking network status...';\n  document.body.appendChild(statusDiv);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"pwa-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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"After calling `window.history.pushState({}, '', '/new-route');`, explicitly invoke your `handleNavigation(window.location);` function (or whatever callback you passed to `installRouter`).","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'call') at installRouter"},{"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.","cause":"Module resolution failure, often due to missing the `.js` extension in the import path, or incorrect pathing in a non-bundled environment.","error":"Error: Cannot find module 'pwa-helpers/router.js' or 'pwa-helpers/network.js'"}],"ecosystem":"npm"}