The official AREA 17 boilerplate


7.1.68 months ago4 years agoMinified + gzip package size for @area17/a17-boilerplate in KB


A17 FE Boilerplate


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.


Via npm: 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


All available tasks are listed in package.json file as npm tasks and are documented in the Wiki


By default, build tasks for A17 Boilerplate live inside the package so that they can be updated as the package is updated. If, in the future, the tasks need to be updated independently of the the A17 Boilerplate development, then they can be ejected using npm run eject.

Supported Browsers

Boilerplate runs mustard test in the head and bottom of the document to test for JavaScript module support to see if the browser is modern or not (see sample.html). Modern browsers are currently considered to be:

  • Safari 11+
  • Edge 16+
  • Chrome 61+
  • FF 60+

Older browsers will have their JavaScript execution halted and load a fall back HTML4CSS

Update Log


  • Updated mustard test fail to have better IE6 support and inserts an "Old browser" message


  • Updated mustard test fail in sample.html
    • now removes style sheets rather than disabling as some versions of IE can't disable a stylesheet but they can remove them
    • fixed the missing window
    • added note about fixing lazy loaded images


  • Added colspan mixin to _grid.scss - the mixin equivalent of the colspan classes


  • Updated A17 helpers dependency to 2.0.2 for updates to resized helper


  • pass through frontend config data to compiled JS
    • passes through essentially as a module and so if unused, isn't in final output
  • pass through smallest breakpoint name to SCSS
  • if no passed through smallest breakpoint in SCSS, SCSS decides better than using index = 1
  • rename black/white list to block/allow in manifest.json
  • rename master branch to main


  • fix svg sprite fetch


  • renames boilerplate.json to frontend.config.json
  • align breakpoint names with Tailwind breakpoint names ('xs', 'md', 'lg', 'xl', 'xxl' )
  • smallest breakpoint doesn't auto output media queries, they're the defaults
  • sample HTML updated to have more efficient order and updated mustard test
  • removes head.js - new mustard test in HTML based on JavaScript module support means a very minimal amount of head.js remains
  • updates babel config to target browsers used in mustard test (so a lot less transpiling)
  • use latest version of A17 JS Helpers


  • Update to depend on "@area17/a17-helpers": "2.0.0",


  • Large re-factor..
    • see http://bp7.dev.area17.com/
    • Boilerplate is now more of a library with optional components
      • run npm init to choose what bits to take
      • BP SCSS now lives in node_modules/ so your project code is your project code
      • JS set up is via A17 helpers
      • Set up is done via boilerplate.json or optional SCSS maps
  • Documentation is lagging behind - blame Mike. If you want the old boiler plate then install 6.2.7. For now http://bp7.dev.area17.com/ is your best bet.
  • More to come!


  • Import unit mixins.


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


  • Including dotenv to correctly read .env vars


  • A17 Helpers version update


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



  • Fix wrong path resolution to default manifest import


  • 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


  • BrowserSync config : use env DEV_URL as proxy if exist


  • Custom BrowserSync config set in project will replace the default config


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


  • Update documentation


  • Update dependencies


  • 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


  • Removed touch class test from head.js


  • Adding CustomEvent polyfill to app.js as corresponding helper is going to be deprecated


  • Update documentation


  • 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.


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



  • Update dependencies (Webpack and Babel)


  • Update dependencies


  • New manifest.json updates to pass through ports to BrowserSync:
    "config": {
      "browsersyncPort": 1312,
      "browsersyncUiPort": 1313


  • 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


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


  • 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


  • 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.


  • Update node-sass so this support Node v11


  • Webpack 4 is now used to generate JS


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


  • Update Babel version to 7.x.x.


  • Update dependencies.


  • Update dependencies.


  • Fix a manifest file path bug.


  • Prevent svgo from removing viewBox attribute from svgs.


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


  • Remove babel-polyfill from app.js by default


  • Webpack config update


  • 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


  • Update icon task so ids of the svg symbols are prefixed with icon--.


  • 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" : [


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


  • Safely update packages
  • Watch images


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

  • In production npm run prod :



  • Add script source map


  • Refactor icon task so it is only using svg-store and svgo (it remove the phantomjs dependency)


  • Add sass source map


  • Use Webpack to watch scripts (other files are still watchting via package watch)


  • Add icon watch and revise some readme info.


  • Updated some instructions


  • The bp 3.0


For publishing to npm, please see this guide.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.