Progressive Web Apps for Rails
This gem only provides a foundation upon which you can build your Progressive Web App. It simplifies adding a service worker and a manifest to your app, so that it can be recognized as an PWA and as such accessed without a network connection.
Google defines Progressive Web Apps as:
- Reliable - Load instantly and never show the downasaur, even in uncertain network conditions.
- This is handled by Progressive Web Apps for Rails.
- Fast - Respond quickly to user interactions with silky smooth animations and no janky scrolling.
- There are two technologies helping you with performance: Turbolinks & AMP. When you are using Turbolinks, use TurbolinksAnimate to get XHR requests + smooth page transitions that add some delight to using to your app. If you want to use AMP, take a look at amp-html, an Accelerated Mobile Pages library for Rails apps.
- Engaging - Feel like a natural app on the device, with an immersive user experience.
- When you think about making your app more engaging, you can't get around user-notifications. OneSignal is a powerful (& free) solution. With OnSignal and notification-pusher-onesignal adding native notification capabilities to your app becomes dead simple.
If a PWA is not enough and you want to bring your Web App into the store - check out NativeGap.
Table of Contents
Installation
Progressive Web Apps for Rails works with Rails 5 onwards. You can add it to your Gemfile
with:
And then execute:
$ bundle
Or install it yourself as:
$ gem install pwa
If you always want to be up to date fetch the latest from GitHub in your Gemfile
:
Usage
Quick start
Run the generators:
$ rails g mozaic:install
$ rails g pwa:install
$ rails g pwa:app -n "App"
Now define your app:
Pwa.configure do |config| config.define_app 'App'end
Add the following to the head
tag of your layout file:
= component 'pwa/manifest', url: request.base_url
Now add the pwa-rails
NPM package and initialize it:
;document
Note: If the name of the service worker is not the default /pwa-sw.js
you can specify a custom path: new ProgressiveWebApp('/custom-path.js')
Lastly, go to your routes file (config/routes.rb
) and mount the Pwa::Engine
class:
mount Pwa::Engine, at: ''
Note: The path Pwa::Engine
is being mounted at, is currently required to be ''
.
Apps
Progressive Web Apps for Rails allows for multiple Progressive Web Apps per Rails app:
Pwa.configure do |config| config.define_app 'Subdomain', ['subdomain.example.com', 'subdomain.lvh.me:3000'] config.define_app 'Example', ['example.com', 'localhost:3000', 'lvh.me:3000']end
Note: You can omit the array of URL scopes if you have just one PWA.
When looking for an app, the first app specified with a matching scope will be used.
Manifest
The app generator generates a manifest file located in the app/views/pwa/apps/manifests
directory. It is accessible through /manifest.json
. You can customize it to your liking.
Offline pages
Progressive Web Apps for Rails automatically stores a copy of the offline page (app/views/pwa/apps/offline/_app.html.erb
) in the users cache, so your app is accessible at all times, even if requested URLs have not been cached yet.
Themes
Progressive Web Apps for Rails simplifies adding themes reflected in browsers to your site. Add the following to the head
tag in your layout file:
= component 'pwa/theme', default: '#000000'
Note: default
falls back to #FFFFFF
.
You can now override the default theme color from your views:
- area :pwa_theme, '#FF0000'
Service worker
The generator also generates a service worker which caches visited pages to the local storage so they can get accessed even if the device has no network connection.
You can customize the page that shows up when a requested page has not been cached by editing the contents of app/views/pwa/offline/index.html.erb
Note: When using Progressive Web Apps for Rails with a service worker provided by a third party service like OneSignal, remove the NPM package and manually import your apps service worker in the third party script:
;
Styles
To detect whether or not your app is currently being used as a Progressive Web App, you can use CSS media queries:
{ /* ... */}
Note: Make sure to use fullscreen
instead of standalone
if that is your PWA display mode.
Configuration
You can configure Pwa by passing a block to configure
. This can be done in config/initializers/pwa.rb
:
Pwa.configure do |config| config.define_app 'App', ['example.com']end
define_app
Define apps with a name and URL scopes.
Release
- Review breaking changes and deprecations in
CHANGELOG.md
. - Change the version in
package.json
andlib/pwa/version.rb
. - Reset
CHANGELOG.md
. - Create a pull request to merge the changes into
master
. - After the pull request was merged, create a new release listing the breaking changes and commits on
master
since the last release. - The release workflow will publish the node package to NPM and GPR and the gem to Rubygems and GPR.
Contributing
We hope that you will consider contributing to Progressive Web Apps for Rails. Please read this short overview for some information about how to get started:
Learn more about contributing to this repository, Code of Conduct
Semantic Versioning
Progressive Web Apps for Rails follows Semantic Versioning 2.0 as defined at http://semver.org.