boilerplate - npm Package Compare versions

Comparing version 0.5.3 to 0.6.0

README.md

+# boilerplate [![NPM version](https://img.shields.io/npm/v/boilerplate.svg?style=flat)](https://www.npmjs.com/package/boilerplate) [![NPM downloads](https://img.shields.io/npm/dm/boilerplate.svg?style=flat)](https://npmjs.org/package/boilerplate) [![Build Status](https://img.shields.io/travis/jonschlinkert/boilerplate.svg?style=flat)](https://travis-ci.org/jonschlinkert/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
+
+- [html5-boilerplate example](#html5-boilerplate-example)
+- [FAQ](#faq)
+  * [Comparison table](#comparison-table)
+- [History](#history)
+- [About](#about)
+  * [Related projects](#related-projects)
+  * [Contributing](#contributing)
+  * [Building docs](#building-docs)
+  * [Running tests](#running-tests)
+  * [Author](#author)
+  * [License](#license)
+
+_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
+
+## Install
+
+Install with [npm](https://www.npmjs.com/):
+
+```sh
+$ npm install --save boilerplate
+```
+
+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][scaffold], 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](http://gruntjs.com/) tasks would be defined.
+
+```js
+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](http://gulpjs.com), [grunt](http://gruntjs.com/), [assemble](https://github.com/assemble/assemble), [metalsmith](https://github.com/segmentio/metalsmith), or even [yeoman](http://yeoman.io), for scaffolding out various parts of a blog, website, web application or whatever you think a boilerplate might be useful for!
+
+## Table of contents
+
+- [html5-boilerplate example](#html5-boilerplate-example)
+- [FAQ](#faq)
+  * [Comparison table](#comparison-table)
+- [History](#history)
+- [About](#about)
+  * [Related projects](#related-projects)
+  * [Contributing](#contributing)
+  * [Building docs](#building-docs)
+  * [Running tests](#running-tests)
+  * [Author](#author)
+  * [License](#license)
+
+_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/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](https://github.com/h5bp/html5-boilerplate).
+
+_(Get hands-on with the [h5bp recipe](./recipes/h5bp))_
+
+**Install h5bp**
+
+First, install `boilerplate` and [html5-boilerplate](https://github.com/h5bp/html5-boilerplate):
+
+```sh
+$ 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](https://github.com/h5bp/html5-boilerplate) project, organized exactly the way the project itself is organized.
+
+```js
+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:
+
+```js
+{
+  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](./docs/terminology.md) for defining and organizing project boilerplates
+* [API](#api) for actually creating boilerplates
+* [documentation](./docs/getting-started.md) and [guide](./docs/guide.md) to help you get started with [authoring](docs/authoring.md) your own boilerplates
+* [website](https://github.com/jonschlinkert/boilerplate) 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](https://github.com/assemble/assemble), [gulp](http://gulpjs.com), [grunt](http://gruntjs.com/), [broccoli](https://github.com/broccolijs/broccoli), and [yeoman](http://yeoman.io).
+
+If you publish a library that works with Boilerplate, please [let us know about it](https://github.com/boilerplates/boilerplates/issues/new?title=boilerplate-%5Bname%20here%5D&body=I%20created%20a%20new%20boilerplate%3A%0A%0A*%20homepage%3A%20%5Bproject%20url%5D%20%0A*%20description%3A%20%5Bboilerplate%20description%5D)!
+
+### 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](https://github.com/jonschlinkert/templates) | Resuable file, code or content which contains "placeholder" values that will eventually be replaced with real values by a rendering (template) engine |
+| [scaffold](https://github.com/jonschlinkert/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 to `boilerplate.targets`. Instead they are added to `boilerplate.scaffolds.default.targets`. As a result there is no need to loop over both `targets` and `scaffolds` at build time
+
+## About
+
+### Related projects
+
+* [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble "Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit")
+* [boilerplate](https://www.npmjs.com/package/boilerplate): Tools and conventions for authoring and publishing boilerplates that can be generated by any build… [more](https://github.com/jonschlinkert/boilerplate) | [homepage](https://github.com/jonschlinkert/boilerplate "Tools and conventions for authoring and publishing boilerplates that can be generated by any build system or generator.")
+* [generate](https://www.npmjs.com/package/generate): Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… [more](https://github.com/generate/generate) | [homepage](https://github.com/generate/generate "Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the robustness and configurability of Yeoman, the expressiveness and simplicity of Slush, and more powerful flow control and composability than either.")
+* [scaffold](https://www.npmjs.com/package/scaffold): Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… [more](https://github.com/jonschlinkert/scaffold) | [homepage](https://github.com/jonschlinkert/scaffold "Conventions and API for creating declarative configuration objects for project scaffolds - similar in format to a grunt task, but more portable, generic and can be used by any build system or generator - even gulp.")
+* [templates](https://www.npmjs.com/package/templates): System for creating and managing template collections, and rendering templates with any node.js template engine… [more](https://github.com/jonschlinkert/templates) | [homepage](https://github.com/jonschlinkert/templates "System for creating and managing template collections, and rendering templates with any node.js template engine. Can be used as the basis for creating a static site generator or blog framework.")
+* [update](https://www.npmjs.com/package/update): Be scalable! Update is a new, open source developer framework and CLI for automating updates… [more](https://github.com/update/update) | [homepage](https://github.com/update/update "Be scalable! Update is a new, open source developer framework and CLI for automating updates of any kind in code projects.")
+* [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb "Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.")
+
+### Contributing
+
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
+
+### Building docs
+
+_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_
+
+To generate the readme and API documentation with [verb](https://github.com/verbose/verb):
+
+```sh
+$ npm install -g verb verb-generate-readme && verb
+```
+
+### Running tests
+
+Install dev dependencies:
+
+```sh
+$ npm install -d && npm test
+```
+
+### Author
+
+**Jon Schlinkert**
+
+* [github/jonschlinkert](https://github.com/jonschlinkert)
+* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
+
+### License
+
+Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
+Released under the [MIT license](https://github.com/jonschlinkert/boilerplate/blob/master/LICENSE).
+
+***
+
+_This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on July 18, 2016._

index.js

@@ -41,3 +41,2 @@ 'use strict';
   this.scaffolds = {};
-  this.targets = {};
 
@@ -118,13 +117,23 @@ if (util.isConfig(options)) {
 
-Boilerplate.prototype.expand = function(boilerplate) {
-  // support anonymous targets
-  if (util.isTarget(boilerplate)) {
-    this.addTarget('target' + (this.count++), boilerplate);
+Boilerplate.prototype.expand = function(config) {
+  // support targets
+  if (util.isTarget(config)) {
+    var name = config.name || 'target' + (this.count++);
+    this.addTarget(name, config);
     return this;
   }
 
-  for (var key in boilerplate) {
-    if (boilerplate.hasOwnProperty(key)) {
-      var val = boilerplate[key];
+  // support scaffolds
+  if (utils.Scaffold.isScaffold(config) && config.name) {
+    this.addScaffold(config.name, config);
+    return this;
+  }
 
+  for (var key in config) {
+    if (key === 'name' || key === 'key') {
+      continue;
+    }
+    if (config.hasOwnProperty(key)) {
+      var val = config[key];
+
       if (this.Scaffold.isScaffold(val)) {
@@ -202,6 +211,10 @@ this.addScaffold(key, val);
   }
-  if (!util.isObject(config)) {
+  if (!utils.isObject(config)) {
     throw new TypeError('expected an object');
   }
 
+  if (!this.scaffolds.hasOwnProperty('default')) {
+    this.scaffolds.default = {targets: {}};
+  }
+
   var Target = this.get('Target');
@@ -220,3 +233,3 @@ var target = new Target(this.options);
   target.addFiles(config);
-  this.targets[name] = target;
+  this.scaffolds.default.targets[name] = target;
   return target;
@@ -277,3 +290,3 @@ };
 Boilerplate.isBoilerplate = function(config) {
-  if (!util.isObject(config)) {
+  if (!utils.isObject(config)) {
     return false;
@@ -296,4 +309,4 @@ }
 
-function emit(name, a, b) {
-  a.on(name, b.emit.bind(b, name));
+function emit(name, provider, receiver) {
+  provider.on(name, receiver.emit.bind(receiver, name));
 }
@@ -300,0 +313,0 @@

package.json

 {
   "name": "boilerplate",
-  "description": "Tools and conventions for authoring and publishing boilerplates that can be generated by any build system or generator.",
-  "version": "0.5.3",
+  "description": "Tools and conventions for authoring and using declarative configurations for project \"boilerplates\" that can be consumed by any build system or project scaffolding tool.",
+  "version": "0.6.0",
   "homepage": "https://github.com/jonschlinkert/boilerplate",
@@ -14,2 +14,4 @@ "author": "Jon Schlinkert (https://github.com/jonschlinkert)",
     "index.js",
+    "LICENSE",
+    "README.md",
     "utils.js"
@@ -29,11 +31,13 @@ ],
     "expand-target": "^0.6.4",
-    "expand-utils": "^0.2.1",
+    "expand-utils": "^0.2.2",
     "is-scaffold": "^0.1.1",
+    "isobject": "^2.1.0",
     "lazy-cache": "^2.0.1",
     "mixin-deep": "^1.1.3",
-    "scaffold": "^0.2.11"
+    "scaffold": "^0.2.13"
   },
   "devDependencies": {
+    "assemble": "^0.16.1",
     "gulp": "^3.9.1",
-    "gulp-eslint": "^2.0.0",
+    "gulp-eslint": "^3.0.1",
     "gulp-format-md": "^0.1.9",
@@ -78,3 +82,3 @@ "gulp-istanbul": "^1.0.0",
   "verb": {
-    "toc": false,
+    "toc": true,
     "layout": "default",
@@ -102,7 +106,6 @@ "tasks": [
       "grunt",
-      "guide",
       "gulp",
       "metalsmith",
       "verb",
-      "verb-readme-generator",
+      "verb-generate-readme",
       "yeoman"
@@ -109,0 +112,0 @@ ],

utils.js

@@ -14,2 +14,3 @@ 'use strict';
 require('expand-target', 'Target');
+require('isobject', 'isObject');
 require('is-scaffold');
@@ -16,0 +17,0 @@ require('mixin-deep', 'merge');

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24570

136.36%

Number of package files

5

25%

Lines of code

290

4.32%

Number of medium quality alerts

1

-50%

Number of lines in readme file

313

Infinity%

Worsened metrics

Dependency count

10

11.11%

Dev dependency count

8

14.29%

Dependency changes

• + Added

  isobject@^2.1.0

• Updated

  expand-utils@^0.2.2

• Updated

  scaffold@^0.2.13