https://github.com/lavas-project/jekyll-pwa
Jekyll plugin for PWA
https://github.com/lavas-project/jekyll-pwa
jekyll jekyll-plugin pwa ruby workbox
Last synced: 2 months ago
JSON representation
Jekyll plugin for PWA
- Host: GitHub
- URL: https://github.com/lavas-project/jekyll-pwa
- Owner: lavas-project
- License: mit
- Created: 2017-11-07T15:42:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-08-29T10:46:53.000Z (almost 3 years ago)
- Last Synced: 2025-04-02T02:16:25.971Z (3 months ago)
- Topics: jekyll, jekyll-plugin, pwa, ruby, workbox
- Language: Ruby
- Homepage:
- Size: 550 KB
- Stars: 107
- Watchers: 6
- Forks: 19
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Jekyll PWA Plugin [](http://badge.fury.io/rb/jekyll-pwa-plugin)
> PWA support for Jekyll
This plugin provides PWA support for Jekyll. Generate a service worker and provides precache and runtime cache with Google Workbox.
Google Workbox has already developed a series of [tools](https://developers.google.com/web/tools/workbox/). If you use Webpack or Gulp as your build tool, you can easily generate a service worker with these tools. But in my blog, I don't want to use even npm, and I want to precache recent 10 posts so that they are offline available to visitors even though these posts were never opened by visitors before. That's why I try to integrate this function in Jekyll build process.
**IMPORTANT** This plugin supports Workbox V5 since `v5.1.4`.
The API of Workbox V5 has changed a lot compared to previous versions, some more powerful functions added too.
**_PLEASE NOTE -> you must update your service worker as described below!_**
This plugin has been used in [my blog](https://xiaoiver.github.io) so that you can see the effect.
## Installation
This plugin is available as a [RubyGem][ruby-gem].
### Option #1
Add `gem 'jekyll-pwa-plugin'` to the `jekyll_plugin` group in your `Gemfile`:
```ruby
source 'https://rubygems.org'
gem 'jekyll'
group :jekyll_plugins do
gem 'jekyll-pwa-plugin'
end
```
Then run `bundle` to install the gem.
### Option #2
Alternatively, you can also manually install the gem using the following command:
```
$ gem install jekyll-pwa-plugin
```
After the plugin has been installed successfully, add the following lines to your `_config.yml` in order to tell Jekyll to use the plugin:
```
plugins:
- jekyll-pwa-plugin
```
## Getting Started
### Configuration
Add the following configuration block to Jekyll's `_config.yml`:
```yaml
pwa:
enabled: false # Optional
sw_src_filepath: service-worker.js # Optional
sw_dest_filename: service-worker.js # Optional
dest_js_directory: assets/js # Required
precache_recent_posts_num: 5 # Optional
precache_glob_directory: / # Optional
precache_glob_patterns: # Optional
- "{js,css,fonts}/**/*.{js,css,eot,svg,ttf,woff}"
- index.html
precache_glob_ignores: # Optional
- sw-register.js
- "fonts/**/*"
```
Parameter | Description
---------- | ------------
enabled | Determines whether a sw will be registered and written to disk. Useful to disable when you run into problems in your development environment. Default is `true`.
sw_src_filepath | Filepath of the source service worker. Defaults to `service-worker.js`
sw_dest_filename | Filename of the destination service worker. Defaults to `service-worker.js`
dest_js_directory | Directory of JS in `_site`. During the build process, some JS like workbox.js will be copied to this directory so that service worker can import them in runtime.
precache_glob_directory | Directory of precache. [Workbox Config](https://developers.google.com/web/tools/workbox/get-started/webpack#optional-config)
precache_glob_patterns | Patterns of precache. [Workbox Config](https://developers.google.com/web/tools/workbox/get-started/webpack#optional-config)
precache_glob_ignores | Ignores of precache. [Workbox Config](https://developers.google.com/web/tools/workbox/get-started/webpack#optional-config)
precache_recent_posts_num | Number of recent posts to precache.
We handle precache and runtime cache with the help of Google Workbox v5.1.4 in service worker.
### Write your own Service Worker
Create a `service-worker.js` in the root path of your Jekyll project.
You can change this source file's path with `sw_src_filepath` option.
Now you can write your own Service Worker with [Workbox APIs](https://developers.google.com/web/tools/workbox/reference-docs/latest/).
Here's what the `service-worker.js` like in my site.
```javascript
// service-worker.js
// set names for both precache & runtime cache
workbox.core.setCacheNameDetails({
prefix: 'my-blog',
suffix: 'v1.0',
precache: 'precache',
runtime: 'runtime-cache'
});
// let Service Worker take control of pages ASAP
workbox.core.skipWaiting();
workbox.core.clientsClaim();
// let Workbox handle our precache list
workbox.precaching.precacheAndRoute(self.__precacheManifest);
// use `NetworkFirst` strategy for html
workbox.routing.registerRoute(
/\.html$/,
new workbox.strategies.NetworkFirst()
);
// use `NetworkFirst` strategy for css and js
workbox.routing.registerRoute(
/\.(?:js|css)$/,
new workbox.strategies.NetworkFirst()
);
// use `CacheFirst` strategy for images
workbox.routing.registerRoute(
/assets\/(img|icons)/,
new workbox.strategies.CacheFirst()
);
// use `StaleWhileRevalidate` third party files
workbox.routing.registerRoute(
/^https?:\/\/cdn.staticfile.org/,
new workbox.strategies.StaleWhileRevalidate()
);
```
## Note
### Generate a manifest.json?
This plugin won't generate a [manifest.json](https://developer.mozilla.org/en-US/docs/Web/Manifest). If you want to support this PWA feature, just add one in your root directory and Jekyll will copy it to `_site`.
### When my site updates...
Since the service worker has precached our assets such as `index.html`, JS files and other static files, we should notify user when our site has something changed. When these updates happen, the service worker will go into the `install` stage and request the newest resources, but the user must refresh current page so that these updates can be applied. A normal solution is showing a toast with the following text: `This site has changed, please refresh current page manually.`.
This plugin will dispatch a custom event called `sw.update` when the service worker has finished the update work. So in your site, you can choose to listen this event and popup a toast to remind users refreshing current page.
# Contribute
Fork this repository, make your changes and then issue a pull request. If you find bugs or have new ideas that you do not want to implement yourself, file a bug report.
# Copyright
Copyright (c) 2017 Pan Yuqi.
License: MIT
[ruby-gem]: https://rubygems.org/gems/jekyll-pwa-plugin