feat($build): Added the support for PWA

README.md

@@ -48,20 +48,23 @@ Create a new `my-app` folder with files for your future project.
 
 ```
 my-app/
-  .gitignore
-  README.md
-  elm-package.json
-  public/
-    favicon.ico
-    index.html
-  src/
-    Main.elm
-    index.js
-    main.css
-  tests/
-    elm-package.json
-    Main.elm
-    Tests.elm
+├── .gitignore
+├── README.md
+├── elm-package.json
+├── elm-stuff
+├── public
+│   ├── favicon.ico
+│   ├── index.html
+│   ├── logo.svg
+│   └── manifest.json
+├── src
+│   ├── Main.elm
+│   ├── index.js
+│   ├── main.css
+│   └── registerServiceWorker.js
+└── tests
+    ├── Tests.elm
+    └── elm-package.json
 ```
 
 You are ready to employ the full power of Create Elm App!

config/webpack.config.prod.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const autoprefixer = require('autoprefixer');
+const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
 const DefinePlugin = require('webpack/lib/DefinePlugin');
 const UglifyJsPlugin = require('webpack/lib/optimize/UglifyJsPlugin');
 const HtmlWebpackPlugin = require('html-webpack-plugin');
@@ -195,6 +196,37 @@ module.exports = {
     // Note: this won't work without ExtractTextPlugin.extract(..) in `loaders`.
     new ExtractTextPlugin({
       filename: cssFilename
-    })
+    }),
+
+    // Generate a service worker script that will precache, and keep up to date,
+    // the HTML & assets that are part of the Webpack build.
+    new SWPrecacheWebpackPlugin({
+      // By default, a cache-busting query parameter is appended to requests
+      // used to populate the caches, to ensure the responses are fresh.
+      // If a URL is already hashed by Webpack, then there is no concern
+      // about it being stale, and the cache-busting can be skipped.
+      dontCacheBustUrlsMatching: /\.\w{8}\./,
+      filename: 'service-worker.js',
+      logger(message) {
+        if (message.indexOf('Total precache size is') === 0) {
+          // This message occurs for every build and is a bit too noisy.
+          return;
+        }
+        if (message.indexOf('Skipping static resource') === 0) {
+          // This message obscures real errors so we ignore it.
+          // https://github.com/facebookincubator/create-react-app/issues/2612
+          return;
+        }
+        console.log(message);
+      },
+      minify: true,
+      // For unknown URLs, fallback to the index page
+      navigateFallback: publicUrl + '/index.html',
+      // Ignores URLs starting from /__ (useful for Firebase):
+      // https://github.com/facebookincubator/create-react-app/issues/2237#issuecomment-302693219
+      navigateFallbackWhitelist: [/^(?!\/__).*/],
+      // Don't precache sourcemaps (they're large) and build asset manifest:
+      staticFileGlobsIgnorePatterns: [/\.map$/, /asset-manifest\.json$/],
+    }),
   ]
 };

package.json

@@ -48,6 +48,7 @@
     "react-error-overlay": "^1.0.10",
     "string-replace-loader": "^1.3.0",
     "style-loader": "^0.18.1",
+    "sw-precache-webpack-plugin": "^0.11.4",
     "url-loader": "^0.5.9",
     "webpack": "^3.5.5",
     "webpack-dev-server": "^2.7.1"

template/README.md

@@ -30,6 +30,10 @@ You can find the most recent version of this guide [here](https://github.com/hal
 - [Setting up API Proxy](#setting-up-api-proxy)
 - [Running tests](#running-tests)
   - [Dependencies in Tests](#dependencies-in-tests)
+- [Making a Progressive Web App](#making-a-progressive-web-app)
+  - [Opting Out of Caching](#opting-out-of-caching)
+  - [Offline-First Considerations](#offline-first-considerations)
+  - [Progressive Web App Metadata](#progressive-web-app-metadata)
 - [Deployment](#deployment)
   - [Static Server](#static-server)
   - [GitHub Pages](#github-pages)
@@ -63,23 +67,28 @@ const db = new PouchDB('mydb');
 ```
 
 ## Folder structure
+
 ```
 my-app/
-  .gitignore
-  README.md
-  elm-package.json
-  public/
-    favicon.ico
-    index.html
-  src/
-    Main.elm
-    index.js
-    main.css
-  tests/
-    elm-package.json
-    Main.elm
-    Tests.elm
+├── .gitignore
+├── README.md
+├── elm-package.json
+├── elm-stuff
+├── public
+│   ├── favicon.ico
+│   ├── index.html
+│   ├── logo.svg
+│   └── manifest.json
+├── src
+│   ├── Main.elm
+│   ├── index.js
+│   ├── main.css
+│   └── registerServiceWorker.js
+└── tests
+    ├── Tests.elm
+    └── elm-package.json
 ```
+
 For the project to build, these files must exist with exact filenames:
 
 - `public/index.html` is the page template;
@@ -317,6 +326,109 @@ To use packages in tests, you also need to install them in `tests` directory.
 elm-app test --add-dependencies elm-package.json 
 ```
 
+## Making a Progressive Web App
+
+By default, the production build is a fully functional, offline-first
+[Progressive Web App](https://developers.google.com/web/progressive-web-apps/).
+
+Progressive Web Apps are faster and more reliable than traditional web pages, and provide an engaging mobile experience:
+
+ * All static site assets are cached so that your page loads fast on subsequent visits, regardless of network connectivity (such as 2G or 3G). Updates are downloaded in the background.
+ * Your app will work regardless of network state, even if offline. This means your users will be able to use your app at 10,000 feet and on the Subway.
+ * On mobile devices, your app can be added directly to the user's home screen, app icon and all. You can also re-engage users using web **push notifications**. This eliminates the need for the app store.
+
+The [`sw-precache-webpack-plugin`](https://github.com/goldhand/sw-precache-webpack-plugin)
+is integrated into production configuration,
+and it will take care of generating a service worker file that will automatically
+precache all of your local assets and keep them up to date as you deploy updates.
+The service worker will use a [cache-first strategy](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network)
+for handling all requests for local assets, including the initial HTML, ensuring
+that your web app is reliably fast, even on a slow or unreliable network.
+
+### Opting Out of Caching
+
+If you would prefer not to enable service workers prior to your initial
+production deployment, then remove the call to `serviceWorkerRegistration.register()`
+from [`src/index.js`](src/index.js).
+
+If you had previously enabled service workers in your production deployment and
+have decided that you would like to disable them for all your existing users,
+you can swap out the call to `serviceWorkerRegistration.register()` in
+[`src/index.js`](src/index.js) with a call to `serviceWorkerRegistration.unregister()`.
+After the user visits a page that has `serviceWorkerRegistration.unregister()`,
+the service worker will be uninstalled. Note that depending on how `/service-worker.js` is served,
+it may take up to 24 hours for the cache to be invalidated.
+
+### Offline-First Considerations
+
+1. Service workers [require HTTPS](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers#you_need_https),
+although to facilitate local testing, that policy
+[does not apply to `localhost`](http://stackoverflow.com/questions/34160509/options-for-testing-service-workers-via-http/34161385#34161385).
+If your production web server does not support HTTPS, then the service worker
+registration will fail, but the rest of your web app will remain functional.
+
+1. Service workers are [not currently supported](https://jakearchibald.github.io/isserviceworkerready/)
+in all web browsers. Service worker registration [won't be attempted](src/registerServiceWorker.js)
+on browsers that lack support.
+
+1. The service worker is only enabled in the [production environment](#deployment),
+e.g. the output of `npm run build`. It's recommended that you do not enable an
+offline-first service worker in a development environment, as it can lead to
+frustration when previously cached assets are used and do not include the latest
+changes you've made locally.
+
+1. If you *need* to test your offline-first service worker locally, build
+the application (using `npm run build`) and run a simple http server from your
+build directory. After running the build script, `create-react-app` will give
+instructions for one way to test your production build locally and the [deployment instructions](#deployment) have
+instructions for using other methods. *Be sure to always use an
+incognito window to avoid complications with your browser cache.*
+
+1. If possible, configure your production environment to serve the generated
+`service-worker.js` [with HTTP caching disabled](http://stackoverflow.com/questions/38843970/service-worker-javascript-update-frequency-every-24-hours).
+If that's not possible—[GitHub Pages](#github-pages), for instance, does not
+allow you to change the default 10 minute HTTP cache lifetime—then be aware
+that if you visit your production site, and then revisit again before
+`service-worker.js` has expired from your HTTP cache, you'll continue to get
+the previously cached assets from the service worker. If you have an immediate
+need to view your updated production deployment, performing a shift-refresh
+will temporarily disable the service worker and retrieve all assets from the
+network.
+
+1. Users aren't always familiar with offline-first web apps. It can be useful to
+[let the user know](https://developers.google.com/web/fundamentals/instant-and-offline/offline-ux#inform_the_user_when_the_app_is_ready_for_offline_consumption)
+when the service worker has finished populating your caches (showing a "This web
+app works offline!" message) and also let them know when the service worker has
+fetched the latest updates that will be available the next time they load the
+page (showing a "New content is available; please refresh." message). Showing
+this messages is currently left as an exercise to the developer, but as a
+starting point, you can make use of the logic included in [`src/registerServiceWorker.js`](src/registerServiceWorker.js), which
+demonstrates which service worker lifecycle events to listen for to detect each
+scenario, and which as a default, just logs appropriate messages to the
+JavaScript console.
+
+1. By default, the generated service worker file will not intercept or cache any
+cross-origin traffic, like HTTP [API requests](#integrating-with-an-api-backend),
+images, or embeds loaded from a different domain. If you would like to use a
+runtime caching strategy for those requests, you can [`eject`](#npm-run-eject)
+and then configure the
+[`runtimeCaching`](https://github.com/GoogleChrome/sw-precache#runtimecaching-arrayobject)
+option in the `SWPrecacheWebpackPlugin` section of
+[`webpack.config.prod.js`](../config/webpack.config.prod.js).
+
+### Progressive Web App Metadata
+
+The default configuration includes a web app manifest located at
+[`public/manifest.json`](public/manifest.json), that you can customize with
+details specific to your web application.
+
+When a user adds a web app to their homescreen using Chrome or Firefox on
+Android, the metadata in [`manifest.json`](public/manifest.json) determines what
+icons, names, and branding colors to use when the web app is displayed.
+[The Web App Manifest guide](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/)
+provides more context about what each field means, and how your customizations
+will affect your users' experience.
+
 ## Deployment
 
 

template/public/index.html

@@ -4,6 +4,12 @@
     <meta charset="utf-8">
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <meta name="theme-color" content="#000000">
+    <!--
+      manifest.json provides metadata used when your web app is added to the
+      homescreen on Android. See https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json">
     <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
     <title>Elm App</title>
 </head>

template/public/manifest.json

@@ -0,0 +1,15 @@
+{
+  "short_name": "Elm App",
+  "name": "Create Elm App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "192x192",
+      "type": "image/png"
+    }
+  ],
+  "start_url": "./index.html",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

template/src/index.js

@@ -1,4 +1,7 @@
 import './main.css';
 import { Main } from './Main.elm';
+import registerServiceWorker from './registerServiceWorker';
 
 Main.embed(document.getElementById('root'));
+
+registerServiceWorker();