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.

What is a scaffold? | gulp-scaffold-example

• The goal
• Install
• Usage
• Examples
• API
• What is a scaffold?
  • Comparison table
• Related projects
• Tests
  • Test coverage
  • Running tests
• Contributing
• Author
• License

(TOC generated by verb using markdown-toc)

The goal

Mainly the following two things:

1. Make it easy to create and publish project scaffolds with reusable templates, styles, themes, data etc.
2. To uncouple these "non-moving-parts", which can easily be described using a declarative configuration, from any particular build system or generator.

(To see the opposite of what this project hopes to achieve, take a look at a generator from Google's Yeoman. Yeoman is a node.js application that generates projects from "scaffolding", which includes templates, project metadata, and so on. But it does so in a way that completely couples these things with application logic, making it difficult or tedious to make the components reusable by anything but yeoman).

Example

The following scaffold "expands" into a configuration object that can be passed to gulp, grunt, assemble, metalsmith, or even yeoman for scaffolding out various parts of a blog or site (like adding a new post, UI component, etc):

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 i scaffold --save

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']}
});

.addTargets

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

Params

• scaffold {Object}: Scaffold object with 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'}
  ]
});

What is a scaffold?

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

What does this project do?

Given the above definition, this project provides an API for creating configuration objects with various details about a scaffold, such as source file paths or glob patterns, destination paths, default settings, and so on.

The resulting object could be described as a "scaffold configuration" or "scaffold manifest".

Comparison table

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

Related 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: Fast, composable, highly extendable project generator for node.js | homepage
• templates: System for creating and managing template collections, and rendering templates with any node.js template engine.… more | homepage
• update: Update | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Tests

Test coverage

As of January 06, 2016:

Statements   : 100% (29/29)
Branches     : 100% (18/18)
Functions    : 100% (3/3)
Lines        : 100% (28/28)

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

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

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016 Jon Schlinkert Released under the MIT license.

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