Skip to content

uiolee/hexo-workbox-build

Repository files navigation

hexo-workbox-build

GitHub Tag GitHub Release GitHub commits since latest release GitHub top language Coverage Status CI Libraries.io dependency status for GitHub repo

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

NPM Version node-lts NPM License NPM Downloads NPM Downloads Libraries.io dependency status for latest release

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.