README
boilerplate 
Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be consumed by any build system or project scaffolding tool.
Table of Contents
(TOC generated by verb using markdown-toc)
Install
Install with npm:
$ npm install --save boilerplate
Welcome to boilerplate! Here you'll find both the tools and conventions for creating project boilerplates.
What does this do?
- Makes it easy to create and publish new projects from boilerplates that have reusable [scaffolds][scaffold], templates, styles, themes, data etc.
- 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 (
siteandblog) - 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!
Table of contents
(TOC generated by verb using markdown-toc)
html5-boilerplate example
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'
}
]
}
}
}
FAQ
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?
- opinionated conventions for defining and organizing project boilerplates
- API for actually creating boilerplates
- documentation and guide to help you get started with authoring your own boilerplates
- website for discovering boilerplates created by the community
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!
Comparison table
Many definitions exist for the terms "boilerplate", "scaffold" and "template". The following definitions describe these concepts as it relates to this project.
| 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. |
History
v0.6.0
removed: targets are no longer added toboilerplate.targets. Instead they are added toboilerplate.scaffolds.default.targets. As a result there is no need to loop over bothtargetsandscaffoldsat build time
About
Related projects
- assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
- boilerplate: Tools and conventions for authoring and publishing boilerplates that can be generated by any build… more | homepage
- generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | 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: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
- verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Building docs
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Running tests
Install dev dependencies:
$ npm install -d && npm test
Author
Jon Schlinkert
License
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb, v0.9.0, on July 19, 2016.