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.

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

(TOC generated by verb using markdown-toc)

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 with npm:

$ npm i scaffold --save

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:

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

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

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

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

As of January 06, 2016:

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

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 06, 2016.