@area17/a17-boilerplate

A17 FE Boilerplate

• Wiki https://code.area17.com/a17/fe-boilerplate/wikis/home
• Issues https://code.area17.com/a17/fe-boilerplate/issues

Introduction

The rebuild of A17 FE Boilerplate.

Highly inspired by kcd-scripts and react-scripts

Installation

No more clone. It is an npm package : https://www.npmjs.com/package/@area17/a17-boilerplate

Via a17-generator

Please see instructions here a17-generator.

Manual install

Go to the project root, and run:

$ npm install @area17/a17-boilerplate

After the package is installed please run:

$ npx a17-bp init

Tasks

All avaliable tasks are listed in package.json file as npm tasks.

Configuration

A17 FE Boilerplate has a bunch of config files located in the /config folder. If not specified, A17 FE Boilerplate will use default configurations with it.

Custom configuration is enabled via adding corresponding configuration file in the right place.

For example, place manifest.json file into the project's frontend folder will have A17 FE Boilerplate use this file instead of the default one in the /config folder.

That is to say, it works the way that it will look for configuration file or use default. No commands for configuration.

You can configure the main webpack config by creating the following file at the root of your project.

• webpack.dev.js : used only on development mode
• webpack.prod.js : used only on production mode
• webpack.all.js : used on both mode
• webpack.bs.js : only used to customize the default browser-sync config

Examples

Customizing entries

You can customize the entries in the manifest.json but you can also customize the entries using a webpack.all.js file :

const path = require('path');

module.exports = {
  entry: { 
      head: path.resolve('frontend/js/head.js'),
      app: path.resolve('frontend/js/app.js'),
      main: path.resolve('frontend/scss/app.scss'),
      oldbrowser: path.resolve('frontend/scss/html4css.scss') 
  }
}

In this example, the compiled files will be : head.js, app.js, main.js and oldbrowser.js.

Customizing browser-sync

You can override the default browser-sync configuration using a webpack.bs.js file at the root of your project :

module.exports = {
    ui: {  port: 3001 },
    ghostMode: false,
    port: 3000,
    server: true
};

This will launch a local server listening to localhost:3000, useful to deal wuth static html/CSS/JS files.

Supported Browsers

Boilerplate runs mustard test in the head of the document to test for basic browser abilities to determine if the browser is modern or not (see 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

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:
  • refactor manageBehaviours method
  • integrate universal createBehavior method
• 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.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)
• browser-sync is now performed using the webpack browser-sync 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:

  {
    "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

  @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 :

  "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):

  {
    "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 :

  {
    "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 :

  {
    "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 guide.