Sprout

Simple project templating & skeletons

To use Sprout via the command line, install the sprout-cli package (github).

Why should you care?

A lot of the time you make projects with similar starting templates/boilerplates. There are a number of different standard boilerplates out there (like h5bp), but everyone has their own preferences and tweaks. The goal of sprout is to allow you to write a base template once that is somewhat configurable where it needs to be then initialize the template with the options you choose from the command line or through a javascript API to get a jumpstart on your project.

We are aware that the yeoman project serves a similar purpose, but built this anyway because we needed a project with a very clean and understandable generator API as well as a public javascript API for integration into other projects, and yeoman does not have either of these.

Usage

Sprout is most commonly manipulated through its command-line interface. However, Sprout was made specifically to be easy to integrate into javascript applications and libraries that create project structures for you. It can be installed locally via npm and used directly in a node project. The API is similar to the CLI interface described above. Each method returns a A+ compliant promise (with extra sugar from when.js).

Installation

$ npm install sprout --save

Usage

To construct a Sprout instance:

import Sprout from 'sprout'
const sprout = new Sprout('/path/where/templates/live')

A Sprout instance has the following public values:

• path: (string) the path where the templates live.
• templates: (object) a dictionary of Template objects.

It also is an instance of EventEmitter and emits a few events for feedback.

Methods

Each method returns an A+ promise. The promise, on success, returns the same sprout instance.

sprout.add(name, src)

Create a new template called name from src.

const name = 'sprout-sprout'
const src = 'git@github.com:carrot/sprout-sprout'

sprout.add(name, src).then((sprout) => {
  console.log('template added!')
})

sprout.remove(name)

Remove an existing template called name.

const name = 'sprout-sprout'

sprout.remove(name).then((sprout) => {
  console.log('template removed!')
})

sprout.init(name, target, options)

Use a template called name and save instance to target.

const name = 'sprout-sprout'
const target = '~/Projects/sprout-sprout-instance'

/*
 * Options:
 * locals {Object} - EJS locals to template.
 * tag {String} - A git tag to generate the template from.
 * branch {String} - A git branch to generate the template from.
 * configPath {String} - Path to a JSON or yaml file with pre-defined values.
 * questionnaire {Function} - Function that returns a promise for an object
 */

const options = {
  locals: {
    foo: 'bar'
  }
}

sprout.init(name, target, options).then((sprout) => {
  console.log('template generated!')
})

sprout.run(name, target, generator, args)

Run a generator in a template called name and on template instance instance at target, optionally with an array of args (or string if just one).

const name = 'mvc'
const target = '~/Projects/mvc-instance'
const generator = 'model'

sprout.run(name, target, generator, 'User').then((sprout) => {
  console.log('a model named `User` was created!')
})

Writing Your Own Templates

For an example, as well as a sprout template that helps you create new sprout templates, be sure to check out sprout-sprout. If you would like a more generic example, check out sprout-example

Ok so enough about how this is used, I'm sure you are super excited at this point to get in there and write a template. Probably more excited than a party gorilla, which is pretty wild. So let's take a look.

First thing you'll want to do is set up your project structure, which will probably look something like this:

├── root          Where the actual template goes.
├── generators    Where generators go.
│   ├── file1
│   └── file2
│   └── file3
└── init.js       The Sprout configuration file.
└── package.json  Optionally, include a package.json file; all
                  dependencies will be installed on init.

init.js

init.js sets the hooks and configuration for your sprout template.

/*
 * This function is executed before any of the configuration happens.
 * It's a good place to put any introductory messages you want to display.
 * It is of course optional, and can be asynchronous.
 */

exports.before = function (utils) {
  console.log('Getting started...')
}

/*
 * Configure is exposed as an array, which accepts any number of
 * arguments. Each argument can be a string or an object. A string
 * will prompt the user directly for that value, and using an object
 * allows you to configure a slightly more customizable prompt.

 * The 'prompt' option in an object has a couple of preset values you
 * conforms to the configuration used by SBoudrias/Inquirer.js, found here:
 * https://github.com/SBoudrias/Inquirer.js#question
 */

exports.configure = [
  {
    type: 'input',
    name: 'foo',
    message: 'What is foo?'
  },
  {
    type: 'input',
    name: 'github_handle',
    message: 'What is your github handle?'
  },
  {
    type: 'confirm',
    name: 'travis',
    message: 'Do you want to utilize Travis CI?',
    default: false
  }
]

/*
 * This function is executed after the configuration info is collected, but
 * before the templates are rendered. It's a good place use user provided config
 * to generate additional config values needed in the template.
 */

exports.beforeRender = function (utils, config) {
  config.foo = 'bar'
  return utils.target.write('foo.jade', 'h1 Hello World!', config)
}

/*
 * This function is executed after the templates are rendered.  It's a good place
 * to do any other custom config you need, like building extra files etc. You
 * have the full power of node at your fingertips here.
 */

exports.after = function (utils, config) {
  return utils.target.rename('foo.jade', 'bar.jade')
}

/*
 * Optionally specify globs to ignore.
 */

exports.ignore = ['fizz.*']

/*
* Optionally specify a defaults object to your templates.
* Helpful for adding locals to use within your templates
*/

exports.defaults = { moment: require('moment') }

We also provide you the power of underscore.string in all of your ejs templates. This means you can run powerful string operations on your user input like:

// given 'user_model' is prompted by your init.js
function <%= S.classify('user_model') %> (foo, bar) {
  // <%= S.classify('user_model') %> constructor!
}

So between this config file and the root folder, you should be able to make anything happen fairly easily. If not, please open up and issue and we'll try to make it happening-er and/or easier for you : )

Hooks

Sprout comes with the following events for you to write custom logic for. Each hook is passed a utilities object for manipulating files in your template. Each of these hooks accept A+ promises as return values. To use these events, export a function for the hook (or multiple hooks) of your choosing in your init.js:

• before - run before prompting for user input; is passed a configuration object as the second argument.
• beforeRender - run after the project configuration is set; is passed a configuration object as the second argument.
• after - run after rendering has completed; is passed a configuration object as the second argument.

The utilities object passed to each hook contains the following functions (each returns a promise):

function	description
utils.copy(from, to)	copy a file or directory recursively at from (relative to the template's base directory) to the path at to (relative to the template's target directory).
utils.src.read(from)	read a file at from (relative to the template's base directory).
utils.target.copy(from, to)	copy a file at from (relative to the template's target directory) to the path at to (relative to the template's target directory).
utils.target.read(from)	read a file at from (relative to the template's target directory).
utils.target.write(to, what, locals)	write what to path to (relative to the template's target directory), optionally with ejs locals at locals.
utils.target.rename(from, to)	rename file at from to path at to (relative to the template's target directory).
utils.target.remove(what)	remove files; pass a path or an array of paths (relative to the template's target directory).
utils.target.exec(cmd, cwd)	run a child process with the target directory set at the current working directory by default; optionally, pass a path to cwd (relative to the target directory).

Generators

Sprout templates may also include "generators": small scripts to be executed on instances of a template. For example, an mvc template may include model, controller, and view generators for quickly stubbing out an model-view-controller application. Generators are passed utils (an instance of the Utils that reads from the base directory and writes to the target directory) in the first argument; any arguments passed to sprout.run() follow. A model generator in an mvc template may look like this:

module.exports = (utils, name) => {
  return utils.src.read('templates/model').then((output) => {
    return utils.target.write(`lib/models/${name}.js`, output, { name: name })
  })
}

These generators are stored in your template's generators folder and can be used with sprout's run method:

sprout.run('mvc', 'model', 'User')

Versioning Templates

Sometimes changes happen and you might want to be able to specify different versions of a single template. Sprout handles this through git tags. To specify which tag to use, simply pass a tag option to sprout's init method.

sprout.init('my-template', '~/Projects/my-template-instance', { tag: '0.1.2' })

init also accepts a branch option for specifying which branch to generate from:

sprout.init('my-template', '~/Projects/my-template-instance', { branch: 'develop' })

Although you are welcome to use whatever versioning system you are comfortable with, we would strongly recommended using semver, the widely accepted standard in package versioning. This will provide you with a clear framework for managing situations when breaking changes have been made to your template.

License & Contributing

• Details on the license can be found here
• Details on running tests and contributing can be found here