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.