hexo-workbox-build

A hexo plugin to run workbox-build and provide convenient features of PWA and service worker.

Feature

• run workbox-build via passing through your custom options. (generateSW mode or injectManifest mode)
• generate the script which using to register service-worker.
• reference the register script into html.
• copy manifest.json from custom path to public\.
• reference the manifest.json via <link> tag in html.

This plugin doesn't provide PWA support ready out of the box.

You need to know how to use workbox-build, configurate workbox strategy and custom your manifest.json.

Install

pnpm add hexo-workbox-build

# npm i hexo-workbox-build

Configuration

Default Configuration

hexo_workbox_build:
  enable: false

  WB_runWorkboxBuild: true
  WB_swDest: ""
  WB_generateSWOptionsPath: ""
  WB_injectManifestOptionsPath: ""

  REG_generateRegister: true
  REG_registerScriptDest: "registerSW.js"
  # REG_registerScriptNjkPath: "" # default to internal nunjucks template

  REG_injector: true
  REG_injectorNjkString: '<script defer src="{{ REG_registerScriptDest }}"></script>'

  MF_copyManifestJsonSrc: ""
  MF_copyManifestJsonDest: ""

  MF_injector: false
  MF_injectorNjkString: '<link rel="manifest" href="{{ MF_cpoyManifestJsonDest }}" />'

Example Configuration

hexo_workbox_build:
  enable: true

  WB_runWorkboxBuild: true
  WB_swDest: "sw.js"
  WB_generateSWOptionsPath: "workbox/genSWOption.js"
  # WB_injectManifestOptionsPath: "workbox/injMfOption.js"

  REG_generateRegister: true
  # REG_registerScriptDest: 'registerSW.js'
  # REG_registerScriptNjkPath: "" # default to internal nunjucks template

  REG_injector: true
  # REG_injectorNjkString: '<script defer src="{{ REG_registerScriptDest }}"></script>'

  MF_copyManifestJsonSrc: "workbox/manifest.json"
  MF_copyManifestJsonDest: "manifest.json"

  MF_injector: false
  # MF_injectorNjkString: '<link rel="manifest" href="{{ MF_cpoyManifestJsonDest }}" />'

Options

enable or disable this plugin

| option name | value type | default value | note | | ----------- | ---------- | ------------- | ------------------------------------------------------------------------------------------------ | | enbale | boolean | false | Control whether to enable hexo-workbox-build. |

ralated to workbox-build

| option name | value type | default value | note | | ------------------------------ | ---------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | WB_runWorkboxBuild | boolean | true | Control whether to run worlbox-build. | | WB_swDest | string | "" | Specify the name and path of service-worker that worlbox-build generated. (relative to public dir). equal to the swDest option in worlbox-build. | | WB_generateSWOptionsPath | string | "" | Need WB_swDest setting.Specify the path of a js file. (relative to your hexo dir), which use default exports the arguments of generatesw-mode of worlbox-build. | | WB_injectManifestOptionsPath | string | "" | Need WB_swDest generatesw-mode setting.Specify the path of a js file. (relative to your hexo dir), which use default exports the arguments of injectmanifest-mode of worlbox-build |

Note: injectmanifest-mode depend on a built sw.js.

It means you need to run generatesw-mode first in hexo-workbox-build.

ralated to register service worker

generate the code of registering service-worker

| option name | value type | default value | note | | --------------------------- | ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | REG_generateRegister | boolean | true | Control whether to generater a javascript, which is use to register service-worker. | | REG_registerScriptDest | string | registerSW.js | Need WB_swDest.Specify the path of the above javascript code generated. (relative to public dir) | | REG_registerScriptNjkPath | string | "" | path of a nunjucks template of the javascript. (relative to your hexo dir)Default template: ./assets/registerScript.njk |

insert the registering code into html

| option name | value type | default value | note | | ----------------------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | REG_injector | boolean | true | Control whether to Inject the above javascript code into html <script>. You can use REG_injectorNjkString to custom it. | | REG_injectorNjkString | string | <script defer src="{{ REG_registerScriptDest }}"></script> | Custom the <scripts> string. |

related to manifest.json

copy your manifest.json into public

If set both MF_copyManifestJsonSrc and MF_copyManifestJsonDest, hexo-workbox-build will copy your manifest.json to public dir.

In fact, you can simply put your manifest.json in source/ dir without using this above feature.

| option name | value type | default value | note | | ------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------- | | MF_copyManifestJsonSrc | string | "" | Specify the path of your manifest.json. (relative to your hexo dir) | | MF_copyManifestJsonDest | string | "" | Specify the destiny path of your manifest.json. (relative to public dir) |

insert a <link> ref to your manifest.json

some themes likes next have the same feature, you may not to use this if you enable this feature in themes.

| option name | value type | default value | note | | ---------------------- | ---------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | MF_injector | boolean | false | need MF_copyManifestJsonDest.control whether to Inject <link> tag into head of html.You can use MF_injectorNjkString option to custom it. | | MF_injectorNjkString | string | <link rel="manifest" href="{{ MF_cpoyManifestJsonDest }}" /> | custom the <link> string. |