boilerplate

Tools and conventions for authoring and publishing boilerplates that can be generated by any build system or generator.

boilerplate

Tools and conventions for authoring and publishing boilerplates that can be generated by any build system or generator.

Welcome to boilerplate! Here you'll find both the tools and conventions for creating project boilerplates.

What does this do?

  1. Makes it easy to create and publish new projects from boilerplates that have reusable scaffolds, templates, styles, themes, data etc.
  2. To uncouple these "non-moving-parts" from any particular build system or generator, so we can easily generate new projects by simply passing the boilerplate config object to your build system or project generator of choice!

Example

In the following example, we define:

  • scaffolds for our marketing and developer sites
  • targets inside each scaffold (site and blog)
  • files configurations inside each "site" and "blog" target

The configuration is similar to how Grunt tasks would be defined.

var boilerplate = require('boilerplate');
 
boilerplate({
  marketing: {
    site: {
      src: 'templates/mktg/*.hbs',
      dest: 'site/'
    },
    blog: {
      src: 'content/blog/*.md',
      dest: 'site/blog/'
    }
  },
  developer: {
    site: {
      src: 'templates/dev/*.hbs',
      dest: 'site/developer'
    },
    blog: {
      src: 'content/dev/blog/*.md',
      dest: 'site/developer/blog/'
    }
  }
});

The Boilerplate library "expands" this configuration into a normalized object that can easily be passed to gulp, grunt, assemble, metalsmith, or even yeoman, for scaffolding out various parts of a blog, website, web application or whatever you think a boilerplate might be useful for!

(TOC generated by verb using markdown-toc)

Just to show how easy it is to convert an existing project into a Boilerplate project using the most popular boilerplate of them all: html5-boilerplate.

(Get hands-on with the h5bp recipe)

Install h5bp

First, install boilerplate and html5-boilerplate:

$ npm i boilerplate && git clone https://github.com/h5bp/html5-boilerplate.git vendor/h5bp

Define the boilerplate

The following examples returns a normalized configuration object for every file in the html5-boilerplate project, organized exactly the way the project itself is organized.

var Boilerplate = require('boilerplate');
var h5bp = new Boilerplate({
  options: {
    cwd: 'vendor/h5bp/dist'
  },
  root: {src: ['{.*,*.*}'],   dest: 'src/'},
  css:  {src: ['css/*.css'],  dest: 'src/'},
  doc:  {src: ['doc/*.md'],   dest: 'src/'},
  js:   {src: ['js/**/*.js'], dest: 'src/'}
});
console.log(h5bp);

Results in the following object:

{
  options: {
    cwd: 'vendor/h5bp/dist'
  },
  config: {},
  targets: {
    root: {
      options: {
        cwd: 'vendor/h5bp/dist'
      },
      files: [
        {
          src: [
            'vendor/h5bp/dist/.DS_Store',
            'vendor/h5bp/dist/.editorconfig',
            'vendor/h5bp/dist/.gitattributes',
            'vendor/h5bp/dist/.gitignore',
            'vendor/h5bp/dist/.htaccess',
            'vendor/h5bp/dist/404.html',
            'vendor/h5bp/dist/apple-touch-icon.png',
            'vendor/h5bp/dist/browserconfig.xml',
            'vendor/h5bp/dist/crossdomain.xml',
            'vendor/h5bp/dist/favicon.ico',
            'vendor/h5bp/dist/humans.txt',
            'vendor/h5bp/dist/index.html',
            'vendor/h5bp/dist/LICENSE.txt',
            'vendor/h5bp/dist/robots.txt',
            'vendor/h5bp/dist/tile-wide.png',
            'vendor/h5bp/dist/tile.png'
          ],
          dest: 'src/',
          options: {
            cwd: 'vendor/h5bp/dist'
          },
          name: 'scaffold'
        }
      ]
    },
    css: {
      options: {
        cwd: 'vendor/h5bp/dist'
      },
      files: [
        {
          src: [
            'vendor/h5bp/dist/css/main.css',
            'vendor/h5bp/dist/css/normalize.css'
          ],
          dest: 'src/',
          options: {
            cwd: 'vendor/h5bp/dist'
          },
          name: 'scaffold'
        }
      ]
    },
    doc: {
      options: {
        cwd: 'vendor/h5bp/dist'
      },
      files: [
        {
          src: [
            'vendor/h5bp/dist/doc/css.md',
            'vendor/h5bp/dist/doc/extend.md',
            'vendor/h5bp/dist/doc/faq.md',
            'vendor/h5bp/dist/doc/html.md',
            'vendor/h5bp/dist/doc/js.md',
            'vendor/h5bp/dist/doc/misc.md',
            'vendor/h5bp/dist/doc/TOC.md',
            'vendor/h5bp/dist/doc/usage.md'
          ],
          dest: 'src/',
          options: {
            cwd: 'vendor/h5bp/dist'
          },
          name: 'scaffold'
        }
      ]
    },
    js: {
      options: {
        cwd: 'vendor/h5bp/dist'
      },
      files: [
        {
          src: [
            'vendor/h5bp/dist/js/main.js',
            'vendor/h5bp/dist/js/plugins.js',
            'vendor/h5bp/dist/js/vendor/jquery-1.11.3.min.js',
            'vendor/h5bp/dist/js/vendor/modernizr-2.8.3.min.js'
          ],
          dest: 'src/',
          options: {
            cwd: 'vendor/h5bp/dist'
          },
          name: 'scaffold'
        }
      ]
    }
  }
}

What is a boilerplate?

A boilerplate is a project with generic, reusable code, files or content that is intended to be used as a starting point for creating new projects.

What does this project provide?

What does this NOT provide?

Workflows and tools for actually generating new projects from a boilerplate. This is a job much better suited for build systems like assemble, gulp, grunt, broccoli, and yeoman.

If you publish a library that works with Boilerplate, please let us know about it!

The following table describes the difference between boilerplates, scaffolds and templates.

type description
template Resuable file, code or content which contains "placeholder" values that will eventually be replaced with real values by a rendering (template) engine
scaffold Consists of one or more templates or source files and serves as a "temporary support structure" that may be used to initialize a new project, or to provide ad-hoc "components" throughout the duration of a project.
boilerplate Boilerplates consist of all of the necessary files required to initialize a complete project.

Install with npm:

$ npm i boilerplate --save
var boilerplate = require('boilerplate');

Boilerplate

Expand a declarative configuration with scaffolds and targets. Create a new Boilerplate with the given options

Params

  • options {Object}

Example

var boilerplate = new Boilerplate();
 
// example usage 
boilerplate.expand({
  jshint: {
    src: ['*.js', 'lib/*.js']
  }
});

.isBoilerplate

Static method, returns true if the given value is an instance of Boilerplate or appears to be a valid boilerplate configuration object.

Params

  • config {Object}: The value to check
  • returns {Boolean}

Example

Boilerplate.isBoilerplate({});
//=> false 
 
var h5bp = new Boilerplate({
  options: {cwd: 'vendor/h5bp/dist'},
  root: {src: ['{.*,*.*}'], dest: 'src/'},
  // ... 
});
Boilerplate.isBoilerplate(h5bp);
//=> true 

.expand

Expand and normalize a declarative configuration into scaffolds, targets, and options.

Params

  • boilerplate {Object}: Boilerplate object with scaffolds and/or targets.
  • returns {Object}

Example

boilerplate.expand({
  options: {},
  marketing: {
    site: {
      mapDest: true,
      src: 'templates/*.hbs',
      dest: 'site/'
    },
    docs: {
      src: 'content/*.md',
      dest: 'site/'
    }
  },
  developer: {
    site: {
      mapDest: true,
      src: 'templates/*.hbs',
      dest: 'site/'
    },
    docs: {
      src: 'content/*.md',
      dest: 'site/docs/'
    }
  }
});

.addScaffold

Add a scaffold to the boilerplate, while also normalizing targets with src-dest mappings and expanding glob patterns in each target.

Params

  • name {String}: the scaffold's name
  • boilerplate {Object}: Scaffold object where each key is a target or options.
  • returns {Object}

Example

boilerplate.addScaffold('assemble', {
  site: {src: '*.hbs', dest: 'templates/'},
  docs: {src: '*.md', dest: 'content/'}
});

.addTarget

Add a target to the boilerplate, while also normalizing src-dest mappings and expanding glob patterns in the target.

Params

  • name {String}: The target's name
  • target {Object}: Target object with a files property, or src and optionally a dest property.
  • returns {Object}

Example

boilerplate.addTarget({src: '*.hbs', dest: 'templates/'});
  • assemble: Assemble is a powerful, extendable and easy to use static site generator for node.js. Used… more | homepage
  • boilerplate: Tools and conventions for authoring and publishing boilerplates that can be generated by any build… more | homepage
  • generate: Fast, composable, highly extendable project generator with a user-friendly and expressive API. | homepage
  • scaffold: Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… more | homepage
  • templates: System for creating and managing template collections, and rendering templates with any node.js template engine.… more | homepage
  • update: Easily keep anything in your project up-to-date by installing the updaters you want to use… more | homepage
  • verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

As of January 17, 2016:

Statements   : 100% (40/40)
Branches     : 100% (24/24)
Functions    : 100% (4/4)
Lines        : 100% (39/39)

Install dev dependencies:

$ npm i -d && npm test

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Jon Schlinkert

Copyright © 2016 Jon Schlinkert Released under the MIT license.


This file was generated by verb on January 17, 2016.