1.2.0 (#44)

* first pass at integrating `offline-plugin`

* first pass at asset hashing (just js & css for now)

* dependency updates

* yarn.lock post-merge

* hashing tweaks/buildout

* asset caching readme coverage

* asset caching readme coverage

* asset caching readme coverage

* postcss-extend integration (#42)

* first pass at postcss-extend support

* resolve build warning

* tidying up (#43)

* tidying up font sizes

* no reason for footer to have an id

* tidy up font sizes

* tidy up header component (viva la BEM)

* words of encouragement

* dependency updates

* only use service worker for production build

* further document offline-plugin removal

* further document offline-plugin removal

* further document offline-plugin removal

* further document offline-plugin removal

* version bump (#45)

.stylelintrc

@@ -1,6 +1,14 @@
 {
   "extends": "stylelint-config-standard",
   "rules": {
+    "at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": [
+          "extend"
+        ]
+      }
+    ],
     "property-no-unknown": [
       true,
       {

README.md

@@ -15,6 +15,7 @@ starbase is a webpack 4, ES6 & PostCSS boilerplate that utilizes some of the jui
   * [cssnext](https://github.com/MoOx/postcss-cssnext)
   * [PostCSS Nested](https://github.com/postcss/postcss-nested)
   * [PostCSS Responsive Type](https://github.com/seaneking/postcss-responsive-type)
+  * [postcss-extend](https://github.com/travco/postcss-extend)
   * [stylelint](https://github.com/stylelint/stylelint)
   * [MQPacker](https://github.com/hail2u/node-css-mqpacker)
 * ...and more!
@@ -61,6 +62,13 @@ npm run build
 
 ## features you may want to remove
 
+### asset hashing
+The assets generated by starbase are [hashed](https://webpack.js.org/guides/caching/) (strings injected into the filenames) as a cache-busting mechanism. JS and CSS assets will receive a new filename for each production build, but other assets (fonts, images, etc) will only be updated when they are modified.
+
+This feature ships with webpack (and the loaders we use), so removing it is pretty straightforward. Simply open up the webpack config files and remove the hashes from the filenames, which should look something like this: `.[hash:8]`.
+
+Removing hashing for production builds is not recommended.
+
 ### build-time cleanup
 
 starbase is setup to clear all contents of `/dist` (where compiled assets are piped into) during each `npm run build`. If you'd like to remove this part of the build process, perform the following steps:
@@ -102,6 +110,31 @@ starbase enforces the [Airbnb JavaScript Style Guide](https://github.com/airbnb/
 
 After completing the steps above, the only rules that eslint will enforce are the ones you define in the `rules` object in `/.eslintrc`.
 
+### service worker caching
+
+starbase uses [offline-plugin](https://github.com/NekR/offline-plugin/) to cache your project assets for offline use. This means that if someone visits your website on [a device that supports service workers](https://caniuse.com/#feat=serviceworkers), they will be able to view your project again, even if their device is offline.
+
+Out of the box, starbase caches everything, because the project is less than 50kb total. If you will be making a larger app, be considerate of your users and limit what you cache-- perhaps avoid caching large images, custom fonts, etc. Check out the [options docs for offline-plugin](https://github.com/NekR/offline-plugin/blob/master/docs/options.md) to learn more.
+
+[Service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers), by design, only function on secure (https) environments. There is no issue with running starbase on an http environment-- the service worker will simply not be utilized.
+
+You may see an info log entry in your console from `offline-plugin` while using the `watch` command, feel free to ignore this. `offline-plugin` is not utilized on the dev server because [it doesn't always play nice with `webpack-dev-server`](https://github.com/NekR/offline-plugin/issues/138). It is intentionally only utilized in production builds.
+
+#### to remove offline-plugin:
+
+1. in `/package.json`, remove the `offline-plugin` dependency
+2. in `/webpack/webpack.config.base.js`, remove all references to `OfflinePlugin` and/or `offline-plugin`
+3. in `/src/app.js`, remove the `import` statement that references `offline-plugin`
+4. delete `/src/app/lib/offline-plugin.js`
+
+_There is no consequence to removing this feature, besides limiting offline access to your project._
+
+#### to disable (but not delete) offline-plugin:
+
+You can disable `offline-plugin` without deleting it from your codebase, so that it's not included in your production code (reduces filesize) but is ready to be re-enabled if you ever want it back.
+
+1. in `/src/app.js`, comment-out the `import` statement that references `offline-plugin`
+
 ## features you may want to know about
 
 ### global css variables

package.json

@@ -1,6 +1,6 @@
 {
   "name": "starbase",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "author": "Brian Staruk <[email protected]>",
   "contributors": [
     {
@@ -33,8 +33,8 @@
     "babel-core": "^6.26.3",
     "babel-eslint": "^8.2.3",
     "babel-loader": "^7.1.4",
-    "babel-preset-env": "^1.6.1",
-    "caniuse-lite": "^1.0.30000832",
+    "babel-preset-env": "^1.7.0",
+    "caniuse-lite": "^1.0.30000839",
     "clean-webpack-plugin": "^0.1.19",
     "css-loader": "^0.28.11",
     "css-mqpacker": "^6.0.2",
@@ -44,16 +44,18 @@
     "eslint-loader": "^2.0.0",
     "eslint-plugin-import": "^2.11.0",
     "eslint-plugin-jsx-a11y": "^6.0.3",
-    "eslint-plugin-react": "^7.7.0",
+    "eslint-plugin-react": "^7.8.1",
     "file-loader": "^1.1.11",
     "html-loader": "^0.5.5",
     "html-webpack-plugin": "^3.2.0",
     "mini-css-extract-plugin": "^0.4.0",
     "node-sass": "^4.9.0",
+    "offline-plugin": "^5.0.3",
     "postcss": "^6.0.22",
     "postcss-cssnext": "^3.1.0",
+    "postcss-extend": "^1.0.5",
     "postcss-import": "^11.1.0",
-    "postcss-loader": "^2.1.4",
+    "postcss-loader": "^2.1.5",
     "postcss-nested": "^3.0.0",
     "postcss-remove-root": "0.0.2",
     "postcss-reporter": "^5.0.0",
@@ -63,9 +65,9 @@
     "stylelint": "^9.2.0",
     "stylelint-config-standard": "^18.2.0",
     "url-loader": "^1.0.1",
-    "webpack": "^4.6.0",
-    "webpack-cli": "^2.0.15",
-    "webpack-dev-server": "^3.1.3",
+    "webpack": "^4.8.2",
+    "webpack-cli": "^2.1.3",
+    "webpack-dev-server": "^3.1.4",
     "webpack-merge": "^4.1.2"
   },
   "dependencies": {

src/app.js

@@ -1,3 +1,6 @@
+// offline-plugin
+import './app/lib/offline-plugin';
+
 // components js
 import Tabs from './components/tabs/Tabs';
 

src/app/app.css

@@ -11,7 +11,7 @@ body {
   max-width: var(--body-width-max);
   background-color: var(--body-bg-color);
   font-family: var(--font-sans);
-  font-size: responsive var(--body-font-size-range);
+  font-size: var(--body-font-size);
   font-range: var(--body-font-range);
   letter-spacing: 0.02rem;
   line-height: 1.25;

src/app/lib/offline-plugin.js

@@ -0,0 +1,3 @@
+import * as OfflinePluginRuntime from 'offline-plugin/runtime'; // eslint-disable-line import/no-extraneous-dependencies
+
+OfflinePluginRuntime.install();

src/app/utilities.css

@@ -0,0 +1,7 @@
+.clearfix {
+  &::after {
+    content: "";
+    display: table;
+    clear: both;
+  }
+}

src/components/footer/footer.css

@@ -1,4 +1,4 @@
-#footer {
-  font-size: 0.95em;
+.footer {
+  font-size: var(--body-font-size-small);
   color: #888;
 }

src/components/header/README.md

@@ -3,9 +3,9 @@ Global header component styles. Requires a square logo (`img`) and level one hea
 
 ## usage
 ```html
-<header id="header">
-  <img src="path/to/logo.png" alt="Required Logo" />
-  <h1>Required Level One Header</h1>
+<header class="header">
+  <img src="path/to/logo.png" alt="Required Logo" class="header__image" />
+  <h1 class="header__title">Required Level One Header</h1>
   <p>Optional intro text.</p>
 </header>
 ```

src/components/header/header.css

@@ -5,10 +5,10 @@
   --header-font-size-full: 2rem;
 }
 
-#header {
+.header {
   position: relative;
 
-  & img {
+  &__image {
     position: absolute;
     left: 0;
     top: 0;
@@ -20,7 +20,7 @@
     }
   }
 
-  & h1 {
+  &__title {
     font-family: var(--font-serif);
     font-size: var(--header-font-size-small);
     font-weight: normal;

src/components/tabs/tabs.css

@@ -1,3 +1,5 @@
+@import "../../app/utilities.css";
+
 :root {
   --tabs-list-height-small: 2rem;
   --tabs-list-height-full: 2.5rem;
@@ -15,6 +17,8 @@
 
   /* tabs list */
   &__list {
+    @extend .clearfix; /* postcss-extend, dig it! */
+
     list-style-type: none;
     margin: 0;
     padding: 0;
@@ -28,12 +32,6 @@
       border-bottom: 2px solid var(--tabs-border-color);
     }
 
-    &::after {
-      content: "";
-      display: table;
-      clear: both;
-    }
-
     & > li {
       float: left;
       margin: 0.5rem 0.5rem 0 0;

src/templates/index.html

@@ -9,9 +9,9 @@
 </head>
 <body>
 <!-- header -->
-<header role="banner" id="header">
-  <img src="images/starbase.png" alt="starbase logo" />
-  <h1>starbase</h1>
+<header role="banner" class="header">
+  <img src="images/starbase.png" alt="starbase logo" class="header__image" />
+  <h1 class="header__title">starbase</h1>
   <p>starbase is an open source webpack 4, Babel (ES6) & PostCSS boilerplate for web developers, with a small footprint and plenty of room for cream and sugar-- make it your own!</p>
 </header>
 
@@ -55,7 +55,7 @@ <h1>starbase</h1>
 </main>
 
 <!-- footer -->
-<footer role="contentinfo" id="footer">
+<footer role="contentinfo" class="footer">
   <p>crafted in boston by <a href="https://brian.staruk.me" title="continue to brian.staruk.me">brian staruk</a> | <a href="https://github.com/bstaruk/starbase" title="learn more about starbase on github">starbase on github</a></p>
 </footer>
 </body>

src/variables/variables.css

@@ -12,11 +12,12 @@
   --font-serif: 'PT Serif', Palatino, 'Palatino Linotype', 'Palatino LT STD', 'Book Antiqua', Georgia, serif;
 
   /* dimensions */
-  --body-font-size-range: 0.9rem 1.05rem;
-  --body-font-range: 34rem 48rem;
-  --body-width-max: 48rem;
+  --body-font-size: responsive 0.9375rem 1.0625rem; /* 15/16 & 17/16 */
+  --body-font-size-small: responsive 0.9375rem 1rem; /* 15/16 & 16/16 */
+  --body-font-range: 34rem 48rem;/* 544/16, 768/16 */
+  --body-width-max: 48rem; /* 768/16 */
 
   /* breakpoints */
-  @custom-media --small only screen and (min-width: 34rem); /* 544px */
-  @custom-media --medium only screen and (min-width: 48rem); /* 768px */
+  @custom-media --small only screen and (min-width: 34rem); /* 544/16 */
+  @custom-media --medium only screen and (min-width: 48rem); /* 768/16 */
 }

webpack/lib/css-prefix-variables.js

@@ -2,10 +2,14 @@ const loaderUtils = require('loader-utils');
 
 module.exports = function cssPrefixVariables(content) {
   const options = loaderUtils.getOptions(this);
+
   if (options.path) {
     this.cacheable();
-    return `@import url("${options.path}");\n\n${content}`;
-  } else {
-    return content;
+
+    // check if first line of content is another import
+    const lineBreak = content.substr(0, 7) === '@import' ? '\n' : '\n\n';
+    return `@import url("${options.path}");${lineBreak}${content}`;
   }
+
+  return content;
 };

webpack/webpack.config.base.js

@@ -7,7 +7,6 @@ module.exports = {
     app: ['./app.js']
   },
   output: {
-    filename: '[name].js',
     path: path.resolve(__dirname, '../dist')
   },
   resolveLoader: {
@@ -62,7 +61,7 @@ module.exports = {
             loader: 'url-loader',
             options: {
               limit: 10000,
-              name: 'images/[name].[ext]'
+              name: 'images/[name].[md5:hash:hex:8].[ext]'
             }
           }
         ]
@@ -74,7 +73,7 @@ module.exports = {
             loader: 'url-loader',
             options: {
               limit: 10000,
-              name: 'fonts/[name].[ext]'
+              name: 'fonts/[name].[md5:hash:hex:8].[ext]'
             }
           }
         ]
@@ -85,7 +84,7 @@ module.exports = {
           {
             loader: 'file-loader',
             options: {
-              name: 'assets/[name].[ext]'
+              name: 'assets/[name].[md5:hash:hex:8].[ext]'
             }
           }
         ]

webpack/webpack.config.dev.js

@@ -11,9 +11,13 @@ const postcssCssnext = require('postcss-cssnext');
 const postcssNested = require('postcss-nested');
 const postcssRemoveRoot = require('postcss-remove-root');
 const postcssResponsiveType = require('postcss-responsive-type');
+const postcssExtend = require('postcss-extend');
 const cssMqpacker = require('css-mqpacker');
 
 module.exports = webpackMerge(webpackConfigBase, {
+  output: {
+    filename: '[name].js'
+  },
   module: {
     rules: [
       {
@@ -26,19 +30,20 @@ module.exports = webpackMerge(webpackConfigBase, {
             options: {
               sourceMap: 'inline',
               plugins: () => [
-                postcssImport,
                 stylelint(),
                 postcssReporter(),
+                postcssImport(),
+                postcssNested(),
                 postcssCssnext({
                   features: {
                     autoprefixer: {
                       grid: false
                     }
                   }
                 }),
-                postcssResponsiveType,
-                postcssNested,
-                postcssRemoveRoot,
+                postcssResponsiveType(),
+                postcssExtend(),
+                postcssRemoveRoot(),
                 cssMqpacker({
                   sort: true
                 })