CM PWA React

Build-time Vite plugin for generating Angular-style PWA artifacts in React/Vite applications.

The plugin generates, after a production build finishes:

• ngsw.json: service-worker manifest built from final emitted files
• ngsw-worker.js: patched Angular service worker copied into the build output

For full project documentation, see docs/.

Installation

npm install --save-dev cm-pwa-react

Basic Usage

cmPwaReact() returns an array of Vite plugins. Spreading it into the plugins list is recommended:

import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import {cmPwaReact} from 'cm-pwa-react';

export default defineConfig({
  plugins: [
    react(),
    ...cmPwaReact()
  ]
});

By default, every generated manifest entry is placed in one app asset group with installMode: 'prefetch' and updateMode: 'prefetch'.

Excluding Files

Use exclude only when a file should not be controlled by the service worker at all:

export default defineConfig({
  plugins: [
    react(),
    ...cmPwaReact({
      exclude: [
        '/assets/ignore-me.js',
        /\/admin\./
      ]
    })
  ]
});

Lazy Asset Groups

For large apps, keep the shell eager and move route chunks/media to lazy caching:

export default defineConfig({
  plugins: [
    react(),
    ...cmPwaReact({
      assetGroups: [
        {
          name: 'app-shell',
          installMode: 'prefetch',
          include: [
            '/index.html',
            /\/assets\/index-.*\.js$/,
            /\/assets\/index-.*\.css$/,
            /\/assets\/rolldown-runtime-.*\.js$/,
            /\/assets\/vendor-react-.*\.js$/,
            /\/assets\/vendor-router-.*\.js$/
          ]
        }
      ],
      fallbackAssetGroup: {
        name: 'lazy-assets',
        installMode: 'lazy'
      }
    })
  ]
});

Files are assigned to the first configured asset group whose include matches and whose exclude does not match. Any file not matched by assetGroups is still included through fallbackAssetGroup, which defaults to {name: 'app', installMode: 'prefetch'}.

Options

type ManifestAssetPattern = string | RegExp;
type AssetGroupMode = 'prefetch' | 'lazy';

interface ManifestAssetGroupOptions {
  readonly name: string;
  readonly installMode?: AssetGroupMode;
  readonly updateMode?: AssetGroupMode;
  readonly include?: ManifestAssetPattern[];
  readonly exclude?: ManifestAssetPattern[];
}

interface NgPWAOptions {
  enabled?: boolean;
  exclude?: ManifestAssetPattern[];
  assetGroups?: ManifestAssetGroupOptions[];
  fallbackAssetGroup?: ManifestAssetGroupOptions;
}

Development

npm.cmd run build
npm.cmd run test
npm.cmd run version

Use npm.cmd on Windows when PowerShell blocks npm.ps1.

More Documentation

• Project overview
• Architecture and API
• Manifest generation
• Build, release, and tests
• Agent guidance

Support

If you run into issues, email [email protected], use the contact form at cristiammercado.com, or open an issue on GitHub.

License

MIT