PWA Helpers

Common errors

• TypeError: Cannot read properties of undefined (reading 'call') at installRouter

  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.
  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'

  cause 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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: After calling `window.history.pushState({}, '', '/new-route');`, explicitly invoke your `handleNavigation(window.location);` function (or whatever callback you passed to `installRouter`).
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install pwa-helpers npm
• yarn add pwa-helpers yarn
• pnpm add pwa-helpers pnpm

Imports

• installRouter
  wrong:

  const { installRouter } = require('pwa-helpers/router');

  correct:

  import { installRouter } from 'pwa-helpers/router.js';

  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
  wrong:

  import updateMetadata from 'pwa-helpers/metadata';

  correct:

  import { updateMetadata } from 'pwa-helpers/metadata.js';

  Symbols are named exports. Direct default imports are not provided by individual modules. The `.js` extension is important.
• installOfflineWatcher
  wrong:

  import { installOfflineWatcher } from 'pwa-helpers/network';

  correct:

  import { installOfflineWatcher } from 'pwa-helpers/network.js';

  For ESM, always include the `.js` extension in the import path. This ensures proper resolution in browsers and some Node.js setups.

Quickstart

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);
}