@area17/a17-boilerplate/README.md

The official AREA 17 boilerplate

# A17 FE Boilerplate

* Wiki [https://code.area17.com/a17/fe-boilerplate/wikis/home](https://code.area17.com/a17/fe-boilerplate/wikis/home)
* Issues [https://code.area17.com/a17/fe-boilerplate/issues](https://code.area17.com/a17/fe-boilerplate/issues)

## Introduction

Instead of opinionated predesigned components, like those provided in Bootstrap and Zurb Foundation, A17 Boilerplate provides a structure and set of ideas to allow quick and consistent set up of a project. It aims to take away the boring set up of "what folder structure do I use?", "how will I generate my CSS?" and "what grid system will I use?" by providing those things out of the box. But, crucially, it then leaves the fun bit of writing the site styles up to you.

## Installation

Via npm: [https://www.npmjs.com/package/@area17/a17-boilerplate](https://www.npmjs.com/package/@area17/a17-boilerplate)

### Via a17-generator

Please see instructions here [a17-generator](https://www.npmjs.com/package/@area17/a17-generator).

### Manual install

Go to the project root, and run:
  ```shell
  $ npm install @area17/a17-boilerplate
  ```

After the package is installed please run:
  ```shell
  $ npx a17-bp init
  ```

## Tasks

All available tasks are listed in `package.json` file as npm tasks and are documented in the [Wiki](https://code.area17.com/a17/fe-boilerplate/wikis/home)

## Supported Browsers

Boilerplate runs [mustard test](http://responsivenews.co.uk/post/18948466399/cutting-the-mustard) in the head of the document to test for basic browser abilities to determine if the browser is modern or not (see [head.js](https://code.area17.com/a17/fe-boilerplate/blob/master/core_files/js/head.js)). Modern browsers are currently considered to be:

* IE11+
* Safari 10+
* Edge 12+
* Chrome 24+
* FF 29+

Older browsers will have their JavaScript execution halted and load a fall back [HTML4CSS](https://github.com/area17/html4css)

**NB** IE11 support will likely be dropped in 2019 with a stricter mustard test.

## Currently planned updates

Currently in no particular order, a list of items currently being discussed/planned.

### Boilerplate specific

* JavaScript evolution:
  * remove IE11 support Q3 2019
* SCSS evolution:
  * deprecate grid float methods
  * add CSS grid methods
  * define and document nomenclature of components
* Compilation tasks:
  * add critical CSS method
  * purge/purify CSS to remove unused styles
  * modern build (ES2015+ build and ES5 with polyfills)
* Documentation
 * dev dependency/dependency - update docs to talk about diff
* Shared 500 pages
* Public release
  * edit documentation, fix gaps

### Broader A17 FE

* Integration with BE:
  * refine faker powered static workflow
  * refine FE block repeater
  * image helpers from AIC
* Design to FE workflow
  * refine process
  * edit documentation
  * assess Figma API for tighter integration
* Toolkit
  * asses bitsrc, patternlab, storylab etc.
  * consider extending Twill guides


## Update Log

**6.2.8**
* Updated webpack config to enable overriding of the optimization setting

**6.2.7**
* Import unit mixins.

**6.2.6**
* Sass deprecation warning : @elseif is deprecated and will not be supported in future Sass versions.
Use "@else if" instead.

**6.2.5**
* Including `dotenv` to correctly read `.env` vars

**6.2.4**
* A17 Helpers version update

**6.2.3**
* pixel font sizes are converted to rems - no change to how we spec typography, just on how the CSS presents the numbers

**6.2.2**
* User Terser instead of Uglify for JS minification. See why : https://github.com/webpack-contrib/uglifyjs-webpack-plugin/blob/master/CHANGELOG.md#breaking-changes

**6.2.1**
* Fix wrong path resolution to default manifest import

**6.2.0**
* Updated merge between default manifest and custom manifest. At the end, we don't to test if a key from manifest exist inside webpack configuration.
* Fixed console outputs. Now we can see infos from webpack in build mode.
* Added verbose mode: We can configure stats mode from webpack by adding verbose argument in the command npm run build --verbosemode. Webpack will output everything from him and plugins.
* Added default alias @ to frontend.source from manifest.json. We can use this alias inside to import files inside .js or .scss

**6.1.5**
* BrowserSync config : use env DEV_URL as proxy if exist

**6.1.4**
* Custom BrowserSync config set in project will replace the default config

**6.1.3**
* Documentation updates. And re-added `id="content"` to the `<main>` element in the `sample.html`.

**6.1.2**
* Update documentation

**6.1.1**
* Update dependencies

**6.1.0**
* added `manageBehaviors` and `createBehavior` with updated `dummyBehavior`
* moved required polyfills to an included file

`manageBehaviors` has been migrated to Boilerplate as it was too specific to our method of triggering functions linked to DOM nodes. This version has been updated to use a `MutationObserver`. Its compatible with existing Boilerplate behaviors (which include a `this.init` and `this.destroy`).

`createBehavior` is new - a new way to create behaviors. Using the this to make your behaviors will give your behavior a few niceties built in:
* access to options set on the container node via `this.options`
* access to helper functions to `getChild` and `getChildren` of the container node
* automatic purging of variables on destroy
* media query scoping, using lifecycle functions `enabled` and `disabled`
* lifecycle functions for debounced `resized` and `mediaQueryUpdated` for custom actions on those events

See `dummyBehavior.js` and `<div data-behavior="dummyBehavior">` in `sample.html` to poke through how to make a new behavior using `createBehavior`

**6.0.4**
* Removed touch class test from head.js

**6.0.3**
* Adding `CustomEvent` polyfill to app.js as corresponding helper is going to be deprecated

**6.0.2**
* Update documentation

**6.0.1**
* Update documentation

**6.0.0**
*Breaking change*

There are the following tasks only now.

* icons : generate icon sprite
* bundle : webpack
* rev : revision assets
* dev : perform 'icons' then 'watch'
* watch : bundle in watch mode and watch for icon change
* build : 'icons' then 'bundle' then 'rev'

This update bring numerous changes :

* No more "styles" or "scripts" tasks : those tasks have been replaced by a task named "bundle"
* No more "clean" task : this is done in the main "bundle" task
* No more "fonts" and "images" tasks to copy the images folder and the fonts folder : this is done in the main "bundle" task
* Style is compiled using webpack with the dart-sass implementation
* Webpack config can be tweak in the project itself (by creating the following files : webpack.dev.js / webpack.prod.js / webpack.all.js at the root of the project)
* BrowserSync is now performed using the webpack BrowserSync plugin : you can easily override the default config by using a custom config in a project webpack.bs.js file).

The watch task has been simplified.
This is only watching for SVG to re-create the icon sprite.

This create quite some changes in the final dist folder :
CSS and JS are now created at the root of the dist folder.
*One important limitation from Webpack : CSS and JS can't have the same name (ie : app.css and app.js are prohibited).*

The rev-manifest.json is still created so Laravel can still use it.

**5.0.5**
* removing uneeded console.log polyfill
* adding NodeList forEach polyfill (corresponding helper is going to be deprecated)
* adding supported browser notes to readme

**5.0.4**
* headjs updates:
  * update mustard test to reflect current SOWs
    * IE11+, Safari 10+, Edge, recent Chrome, recent FF
      https://caniuse.com/#compare=ie+10,ie+11,safari+9,safari+10.1&compare_cats=JS,JS%20API
  * conditionally include picturefill via feature detection as only IE11 needs it
  * removed touch device testing (bad practice)

**5.0.3**
* Update dependencies (Webpack and Babel)

**5.0.2**
* Update dependencies

**5.0.1**
* New manifest.json updates to pass through ports to BrowserSync:

```json
  {
    "config": {
      "browsersyncPort": 1312,
      "browsersyncUiPort": 1313
    }
  }
```

**5.0.0**
* Added new type styles handing with baseline-baseline fixing and margin functions to space baseline-baseline. See ttps://codepen.io/13twelve/pen/WYgrYE?editors=1000

**4.1.2**
* Update Webpack to latest version and remove hardcoded 'frontend' folder in watch task. (There are still some hardcoded 'frontend' to be removed)

**4.1.1**
* Updated `breakpoint` mixin to help generate IE11 and hover based breakpoints

  ```scss
  @include breakpoint('medium+') {
    // styles to be given to browsers at `medium` and above
  }
  @include breakpoint(null,'hover') {
    // styles to be given to devices with mouse pointers
  }
  @include breakpoint(null,'ie11') {
    // styles to be given to be given to IE11
  }
  @include breakpoint('medium+','hover') {
    // styles to be given to browsers at `medium` and above that have mouse pointers
  }
  @include breakpoint('medium+','ie11') {
    // styles to be given to ie11 at `medium` and above
  }
  ```

**4.1.0**
* Add a way to specify custom entry points in the webpack config via the manifest :

  ```json
  "scripts": {
    "app.js": "js/app.js",
    "map.js": "js/map.js",
    "head.js": "js/head.js"
  }
  ```

  If no "scripts" are found it will fallback on the js/app.js and the js/head.js file.

**4.0.1**
* Update node-sass so this support Node v11

**4.0.0**
* Webpack 4 is now used to generate JS

**3.2.1**
* Rev asset task: add a way to pass files into rev task (in addition to default .css and .js files)

**3.2.0**
* Update Babel version to 7.x.x.

**3.1.1**
* Update dependencies.

**3.1**
* Update dependencies.

**3.0.3**
* Fix a manifest file path bug.

**3.0.2**
* Prevent svgo from removing viewBox attribute from svgs.

**3.0.1**
* Exclude a17-helpers package from being compiled by babel (needs to install latest a17-helpers package which is compiled already).

**3.0.0-rc.7**
* Remove babel-polyfill from app.js by default

**3.0.0-rc.6**
* Webpack config update

**3.0.0-rc.5**
* Scripts and Watch tasks must be plugged to the dist folder config via the manifest
* Fonts and Images tasks : empty the folder before copying
* Remove unused packages

**3.0.0-rc.4**
* Update icon task so ids of the svg symbols are prefixed with `icon--`.

**3.0.0-rc.3**
* Add non-frontend file watch support. In `manifest.json`, just add `bs` options to `config` like the following example (it is using relative path to the root of `frontend` folder):

  ```json
  {
    "config": {
      "bs" : {
        "watchExtra" : [
          "./*.php"
        ]
      }
    }
  }
  ```

**3.0.0-rc.2**
* Fix warning in Sass, typography mixin : "&&" means two copies of the parent selector. You probably want to use "and" instead.

**3.0.0-rc.1**
* Safely update packages
* Watch images

**3.0.0-beta.8**
* Clean dist folder before doing a build
* Add the rev task : a rev-manifest.json file will be added at the root of the dist folder to map assets with revisioned ones
* In dev the rev-manifest.json will look like this `npm run build` :

  ```json
  {
    "styles/app.css":"styles/app.css",
    "styles/html4css.css":"styles/html4css.css",
    "scripts/app.js":"scripts/app.js",
    "scripts/head.js":"scripts/head.js"
  }
  ```

* In production `npm run prod` :

  ```json
  {
    "styles/app.css":"styles/app-7ad77318e2.css",
    "styles/html4css.css":"styles/html4css-894eb0106a.css",
    "scripts/app.js":"scripts/app-e82b5c7421.js",
    "scripts/head.js":"scripts/head-b39adeb404.js"
  }
  ```

**3.0.0-beta.7**
* Add script source map

**3.0.0-beta.6**
* Refactor icon task so it is only using svg-store and svgo (it remove the phantomjs dependency)

**3.0.0-beta.5**
* Add sass source map

**3.0.0-beta.4**
* Use Webpack to watch scripts (other files are still watchting via package watch)

**3.0.0-beta.3**
* Add icon watch and revise some readme info.

**3.0.0-beta.2**
* Updated some instructions

**3.0.0-beta.1**
* The bp 3.0

#### Publish
For publishing to npm, please see [this](https://docs.npmjs.com/getting-started/publishing-npm-packages) guide.