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.

Install

Install with npm:

$ npm install --save scaffold

What is a scaffold? | gulp-scaffold-example

What is a scaffold?

There are many definitions for the word "scaffold", here a scaffold is defined as: a declarative configuration for one or more templates or source files, which are intended to serve as a "temporary support structure" to be used for initializing a new project, providing ad-hoc "components" throughout the duration of a project, and so on.

A typical scaffold configuration might include:

• paths or glob patterns for source files or templates
• destination paths or directories to use for generated files
• data for rendering templates
• options

See the comparison table for more information.

Example scaffold

The following scaffold configuration expands into an object that can be passed to gulp, grunt, assemble, metalsmith, yeoman or any other build system for scaffolding out various parts of a blog or site:

var Scaffold = require('scaffold');
var scaffold = new Scaffold({
  posts: {
    src: 'templates/post.md',
    dest: 'blog/' 
  },
  components: {
    cwd: 'content',
    src: ['templates/*.hbs'],
    dest: 'blog/'
  }  
});

Example result

The above scaffold might expand into something like the following:

{
  options: {},
  blog: {
    options: {cwd: 'blog'},
    files: [
      {
        src: ['content/post.md', 'content/about.md'],
        dest: 'src/posts/'
      },
      {
        src: ['data/ipsum.json'],
        dest: 'src/data/'
      }
    ]
  },
  components: {
    options: {cwd: 'ui'},
    files: [
      {
        options: {cwd: 'templates/layouts'},
        src: ['default.hbs', '3-column.hbs'],
        dest: 'src/templates/layouts'
      },
      {
        options: {cwd: 'templates/components'},
        src: ['button.hbs', 'modal.hbs', 'navbar.hbs'],
        dest: 'src/templates/partials'
      },
      {
        src: ['scripts/button.js'],
        dest: 'src/assets/js/'
      },
      {
        src: ['data/ipsum.json'],
        dest: 'src/assets/data/'
      }
    ]
  }
}

Since we're just creating an object (with zero application logic), anything can obviously be extended, overridden, etc.

Install

Install with npm:

$ npm install --save scaffold

Usage

Create an instance of scaffold:

var Scaffold = require('scaffold');
var foo = new Scaffold({
  // config/options here  
});

Scaffold uses expand-target and expand-files as dependencies. Visit those projects for the full range of available features and options:

Examples

The following are just a few random examples of what a scaffold could be, but there are many more use cases.

Blog posts

Create a scaffold for adding blog posts to a project:

var blog = new Scaffold({
  post: {
    cwd: 'content',
    src: 'content/post.md', 
    dest: 'src/posts/'
  }
});

UI components

Create a scaffold for adding UI components to a project:

var components = new Scaffold({
  foo: {
    options: {cwd: 'scaffolds'},
    files: [
      {src: 'templates/component.hbs', dest: 'src/templates/'},
      {src: 'scripts/component.js', dest: 'src/scripts/'},
      {src: 'styles/component.css', dest: 'src/styles/'},
    ]
  }
});

API

Scaffold

Create a new Scaffold with the given options

Params

• options {Object}

Example

var scaffold = new Scaffold({cwd: 'src'});
scaffold.addTargets({
  site: {src: ['*.hbs']},
  blog: {src: ['*.md']}
});

.isScaffold

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

Params

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

Example

Scaffold.isScaffold({});
//=> false

var blog = new Scaffold({
  post: {
    src: 'content/post.md',
    dest: 'src/posts/'
  }
});
Scaffold.isScaffold(blog);
//=> true

.addTargets

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

Params

• targets {Object}: Object of targets, options, or arbitrary properties.
• returns {Object}

Example

scaffold.addTargets({
  site: {src: '*.hbs', dest: 'templates/'},
  docs: {src: '*.md', dest: 'content/'}
});

.addTarget

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

Params

• name {String}
• config {Object}
• returns {Object}

Example

scaffold.addTarget('foo', {
  src: 'templates/*.hbs',
  dest: 'site'
});

// other configurations are possible
scaffold.addTarget('foo', {
  options: {cwd: 'templates'}
  files: [
    {src: '*.hbs', dest: 'site'},
    {src: '*.md', dest: 'site'}
  ]
});

.Target

Getter/setter for the Target constructor to use for creating new targets.

• returns {Function}: Returns the Target constructor to use for creating new targets.

Example

var Target = scaffold.get('Target');
var target = new Target();

.name

Getter/setter for scaffold.name. The name property can be set on the options or directly on the instance.

• returns {Function}: Returns the Target constructor to use for creating new targets.

Example

var scaffold = new Scaffold({name: 'foo'});
console.log(scaffold.name);
//=> 'foo'

// or
var scaffold = new Scaffold();
scaffold.options.name = 'bar';
console.log(scaffold.name);
//=> 'bar'

// or
var scaffold = new Scaffold();
scaffold.name = 'baz';
console.log(scaffold.name);
//=> 'baz'

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

• breaking change: targets are now stored on the targets object
• feature: now emits files when a files object is expanded.

Related projects

You might also be interested in these projects:

• 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: The Santa Claus machine for GitHub projects. Scaffolds out new projects, or creates any kind… 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

Contributing

This document was generated by verb-readme-generator (a verb generator), please don't edit directly. Any changes to the readme must be made in .verb.md. See Building Docs.

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

Or visit the verb-readme-generator project to submit bug reports or pull requests for the readme layout template.

Building docs

(This document was generated by verb-readme-generator (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

Generate readme and API documentation with verb:

$ npm install -g verb verb-readme-generator && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb, v0.9.0, on June 30, 2016.