Initial commit

Author: Karen Baney

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Karen Baney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,188 @@
+# vue-cli-plugin-workbox-pwa
+A Vue CLI Plugin with advanced support for workbox 6.x and Vue 3. Includes the ability to debug the service worker locally.
+
+How is this different from the vue-cli-plugin-pwa?
+- vue-cli-plugin-pwa depends on register-service-worker but this does not. The register-service-worker makes several assumptions about how the PWA should work, but this does not meet advanced use cases like cached apis, cache first, etc.
+- vue-cli-plugin-pwa does not provide a way to easily debug the service worker. This plugin does. It makes use of a new environment variable to enable NODE_ENV=development and injecting the manifest with customizations.
+- We started with some of the manifest features of vue-cli-plugin-pwa. Because this is a more fully featured pwa, we start with the assumption that InjectManifest mode of Workbox is needed.
+
+## Set up
+The scripts commands expects a global install of `npm serve`.
+
+Run: `npm install -g serve`.
+
+## Configuration
+
+Configuration is handled via the `pwa` property of either the `vue.config.js`
+file, or the `"vue"` field in `package.json`.
+
+- **pwa.workboxPluginMode**
+
+  This allows you to choose between the two modes supported by the underlying
+  [`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin).
+
+  - `'InjectManifest'` (default), allows you to start with an existing service worker file,
+  and creates a copy of that file with a "precache manifest" injected into it.
+
+  - `'GenerateSW'` will lead to a new service worker file being created
+  each time you rebuild your web app.
+
+  The "[Which Plugin to Use?](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#which_plugin_to_use)"
+  guide can help you choose between the two modes.
+
+- **pwa.workboxOptions**
+
+  These options are passed on through to the underlying `workbox-webpack-plugin`.
+
+  For more information on what values are supported, please see the guide for
+  [`GenerateSW`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_generatesw_config)
+  or for [`InjectManifest`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_injectmanifest_config).
+
+- **pwa.name**
+
+  - Default: "name" field in `package.json`
+
+    Used as the value for the `apple-mobile-web-app-title` meta tag in the generated HTML. Note you will need to edit `public/manifest.json` to match this.
+
+- **pwa.themeColor**
+
+  - Default: `'#4DBA87'`
+
+- **pwa.msTileColor**
+
+  - Default: `'#000000'`
+
+- **pwa.appleMobileWebAppCapable**
+
+  - Default: `'no'`
+
+    This defaults to `'no'` because iOS before 11.3 does not have proper PWA support. See [this article](https://medium.com/@firt/dont-use-ios-web-app-meta-tag-irresponsibly-in-your-progressive-web-apps-85d70f4438cb) for more details.
+
+- **pwa.appleMobileWebAppStatusBarStyle**
+
+  - Default: `'default'`
+
+- **pwa.assetsVersion**
+
+  - Default: `''`
+
+    This option is used if you need to add a version to your icons and manifest, against browser’s cache. This will append `?v=<pwa.assetsVersion>` to the URLs of the icons and manifest.
+
+- **pwa.manifestPath**
+
+  - Default: `'manifest.json'`
+
+    The path of app’s manifest. If the path is an URL, the plugin won't generate a manifest.json in the dist directory during the build.
+
+- **pwa.manifestOptions**
+
+  - Default: `{}`
+
+    The object will be used to generate the `manifest.json`
+
+    If the following attributes are not defined in the object, the options of `pwa` or default options will be used instead.
+      - name: `pwa.name`
+      - short_name: `pwa.name`
+      - display: `'standalone'`
+      - theme_color: `pwa.themeColor`
+      - start_url: `'/'`
+
+        By default, the start url is set to '/'. If it is set to '.', it will work fine in a web browser or when installed on Windows, but will result in a blank when installed on iOS or Android.
+
+        The router will alse need to have an entry for `path: '/'`. This will meet the requirements for a good `start_url` in Lighthouse.
+
+- **pwa.manifestCrossorigin**
+
+  - Default: `undefined`
+
+    Value for `crossorigin` attribute in manifest link tag in the generated HTML. You may need to set this if your PWA is behind an authenticated proxy. See [cross-origin values](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#attr-crossorigin) for more details.
+
+- **pwa.iconPaths**
+
+  - Defaults:
+
+    ```js
+    {
+      faviconSVG: 'img/icons/favicon.svg',
+      favicon32: 'img/icons/favicon-32x32.png',
+      favicon16: 'img/icons/favicon-16x16.png',
+      appleTouchIcon: 'img/icons/apple-touch-icon-152x152.png',
+      maskIcon: 'img/icons/safari-pinned-tab.svg',
+      msTileImage: 'img/icons/msapplication-icon-144x144.png'
+    }
+    ```
+
+    Change these values to use different paths for your icons. You can use `null` as a value and that icon will not be included.
+
+### Example Configuration
+
+```js
+// Inside vue.config.js
+module.exports = {
+  // ...other vue-cli plugin options...
+  pwa: {
+    name: 'My App',
+    themeColor: '#4DBA87',
+    msTileColor: '#000000',
+    appleMobileWebAppCapable: 'yes',
+    appleMobileWebAppStatusBarStyle: 'black',
+
+    manifestOptions: {
+      start_url: '/'
+    },
+    // configure the workbox plugin
+    workboxPluginMode: 'InjectManifest',
+    workboxOptions: {
+      // swSrc is required in InjectManifest mode.
+      swSrc: './src/sw.js',
+      swDest: 'service-worker.js',
+      // ...other workbox options
+    }
+  }
+}
+```
+
+## Installing in an Already Created Project
+
+``` sh
+vue add workbox-pwa
+```
+
+## Injected dependencies and devDependencies
+
+```
+"dependencies": {
+  "workbox-cacheable-response": "^6.1.5",
+  "workbox-core": "^6.1.5",
+  "workbox-expiration": "^6.1.5",
+  "workbox-routing": "^6.1.5",
+  "workbox-strategies": "^6.1.5",
+  "workbox-window": "^6.1.5"
+},
+"devDependencies": {
+  "workbox-webpack-plugin": "^6.1.5"
+}
+```
+
+## Injected webpack-chain Rules
+
+- `config.plugin('workbox')`
+- `config.plugin('html')` title attribute is added to match the pwa.name
+
+## Injected files
+
+- **public/img/**
+    Default app icons are added.
+- **public/**
+    Default robots.txt is added.
+- **src/sw.js**
+    Default service worker file is added with:
+    - common caching scenarios for index.html, css, js, images.
+    - Workbox's syntax for injecting the manifest. `precacheAndRoute(self.__WB_MANIFEST)`
+    - Workbox clear cache for outdated versions of Workbox. `cleanupOutdatedCaches()`
+-
+
+
+
+## License
+MIT

generator/index.js

@@ -0,0 +1,43 @@
+module.exports = (api, options, rootOptions) => {
+  api.extendPackage({
+    scripts: {
+      'pwa-build': 'vue-cli-service build --mode pwalocalserve',
+      'pwa-serve': 'npm run pwa-build && serve -s dist -l 8080'
+    },
+    dependencies: {
+      'workbox-cacheable-response': '^6.1.5',
+      'workbox-core': '^6.1.5',
+      'workbox-expiration': '^6.1.5',
+      'workbox-routing': '^6.1.5',
+      'workbox-strategies': '^6.1.5',
+      'workbox-window': '^6.1.5'
+    },
+    devDependencies: {
+      'workbox-webpack-plugin': '^6.1.5'
+    }
+  })
+
+  api.render('./template')
+
+  // Inject service worker registration into main.js/.ts
+  const importRegister = `import register from './service-worker/register-service-worker'`
+  api.onCreateComplete(() => {
+    // inject to main.js
+    const fs = require('fs')
+    const ext = api.hasPlugin('typescript') ? 'ts' : 'js'
+    const mainPath = api.resolve(`./src/main.${ext}`)
+
+    // get existing content
+    let contentMain = fs.readFileSync(mainPath, { encoding: 'utf-8' })
+    const lines = contentMain.split(/\r?\n/g).reverse()
+
+    // inject import
+    const lastImportIndex = lines.findIndex(line => line.match(/^import/))
+    lines[lastImportIndex] += importRegister
+
+    // modify add to content
+    const addedContent = `register()`
+    contentMain = lines.reverse().join(`\n${addedContent}\n`)
+    fs.writeFileSync(mainPath, contentMain, { encoding: 'utf-8' })
+  })
+}

generator/template/_env

@@ -0,0 +1,7 @@
+---
+extend: '@vue/cli-service/generator/template/_env'
+---
+
+<%# REPLACE %>
+VUE_APP_PWA_LOCAL_SERVE=false
+<%# END_REPLACE %>

generator/template/_env.pwalocalserve

@@ -0,0 +1,3 @@
+NODE_ENV=development
+VUE_APP_DEBUG=true
+VUE_APP_PWA_LOCAL_SERVE=true

generator/template/main.js

@@ -0,0 +1,2 @@
+import register from './service-worker/register-service-worker' // registers service worker
+register()

generator/template/public/img/icons/android-chrome-192x192.png

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow:

generator/template/public/img/icons/android-chrome-512x512.png

@@ -0,0 +1,65 @@
+import { Workbox } from 'workbox-window'
+
+// const autoUpdate = async (registration: ServiceWorkerRegistration | undefined) => {
+//   setInterval(async () => {
+//     try {
+//       /* eslint-disable-next-line no-unused-expressions */
+//       await registration?.update()
+//     } catch (err) {
+//       /* eslint-disable-next-line no-console */
+//       console.log(`sw: registration autoUpdate failed: ${err}`)
+//     }
+//   }, 1000 * 60 * 60)
+// }
+
+// const manualUpdateAvailable = (registration: ServiceWorkerRegistration | undefined) => {
+//   // Wires up an event that we can listen to in the app. Example: listen for available update and prompt user to update.
+//   document.dispatchEvent(
+//     new CustomEvent('swUpdated', { detail: registration }))
+// }
+
+const register = async () => {
+  if ('serviceWorker' in navigator) {
+    // Workbox combines the ./src/sw.js file and injected manifest into the servicer-worker.js file in /dist
+    // Uses vue.config.js workboxOptions.swSrc for the location of sw.js and swDest for the output location of 'service-worker.js'.
+    // You can override the file names and locations by changing the values of workboxOptions in vue.config.js.
+    const wb = new Workbox(`${process.env.BASE_URL}service-worker.js`)
+
+    // wire up instance of registration so we can take further action on it.
+    const registration = await wb.register()
+    console.log(`sw: waiting: ${registration.waiting}`)
+
+    // autoUpdate(registration)
+
+    // wb.addEventListener('activated', async (event) => {
+    //   if (event.isUpdate) {
+    //     // event.isUpdate=true means the service worker was already registered and there is a new version available.
+
+    //     // this only triggers self.skipWaiting. It still doesn't force the app to update. See /composables/use-service-worker.ts for updating app.
+    //     wb.messageSkipWaiting()
+
+    //     // Wires up an event that we can listen to in the app for manual updates. Example: listen for available update and prompt user to update.
+    //     manualUpdateAvailable(registration)
+    //   } else {
+    //     // first time use when event.isUpdate = false
+    //     // service worker should claim the client immediately since its the first install.
+    //     wb.messageSW({ type: 'CLIENTS_CLAIM' })
+    //     /* eslint-disable-next-line no-console */
+    //     console.log('sw: clientsClaim called.')
+    //   }
+    // })
+
+    // // This is the code piece that GenerateSW mode can't provide for us.
+    // // This code listens for the user's confirmation to update the app.
+    // wb.addEventListener('message', (event) => {
+    //   /* eslint-disable-next-line no-console */
+    //   console.log('sw: message event listener hit.')
+    //   if (event.data && event.data.type === 'SKIP_WAITING') {
+    //     /* eslint-disable-next-line no-console */
+    //     console.log('sw: message SKIP_WAITING called.')
+    //   }
+    // })
+  }
+}
+
+export default register