Sprout

Simple new project templating

Note: This project is in early development and is not currently in a useable state, although you are more than welcome to follow along with development if you'd like!

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.

There is another project called grunt-init that does just about the same thing, but after experimenting with it a bit, we weren't huge fans of the API or the way that it was set up.

Installation

npm install sprout -g

CLI Usage

Sprout can be used directly through the command line to intitialize projects. Once installed, it exposes the sprout binary, which you can use to add, remove, and/or use your templates. The commands are more or less what you would expect, and are listed below. For reference, words in bold are necessary to type out as-is, words in italic represent placeholders for user input, and words in brackets represent optional arguments.

Command params in [brackets] are optional, and in <angle_brackets> are required.

Add Template

Command Syntax: sprout add [name] <clone_url>
Description: Adds a template to your repertoire. Name represents how you would like the template to be named within sprout, and clone url is a url that git clone could be run with and it would be successful. If no name is provided, sprout will use the last piece of the clone url as the name.

Remove Template

Command Syntax: sprout remove <name>
Description: Removes the template with the specified name from sprout.

List Templates

Command Syntax: sprout list
Description: Lists all templates that you have added to sprout.

Initialize Template

Command Syntax: sprout init <name> [path]
Description: Initializes the template with the given name at the given path. If no path is provided it will create a new folder with the same name as the template in the current working directory. If there already is one, it will throw an error.

Sprout also comes with a man page and will display a help menu as a refresher on these commands if you type something wrong.

Javascript API

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. Example code given in coffeescript:

path = require 'path'
sprout = require 'sprout'

# Adding a template
# -----------------
sprout.add 'node', 'https://github.com/carrot/sprout-node', (err, res) ->
  if err then return console.error(err)
  console.log 'template added!'

# removing a template
# -------------------
sprout.remove 'node', (err, res) ->
  if err then return console.error(err)
  console.log 'template removed!'

# listing templates
# -----------------

# this comes back as a js object
templates = sprout.list()

# this comes back as a formatted and colored string inteded to
# to be printed to the command line
console.log sprout.list(pretty: true)

# initializing a template
# -----------------------

sprout.init 'node', path.join(process.cwd(), 'new_project'), (err, res) ->
  if err then return console.error(err)
  console.log 'project structure initialized!'

# other things
# ------------

# returns the path that templates are stored in
console.log sprout.path()

# returns the path of the template name passed in
console.log sprout.path('node')

Writing Your Own Templates

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
`- files...
init.coffee
readme.md
license.md

So a folder called root where the actual template goes, an init.coffee where we'll set up the config and stuff, and then any other files you need like a readme and license, which will not be included with the template. If you don't want any config options, you don't even need the init.coffee, just the root folder with the files in it and that's it. But let's assume you are after some additional configuration and jump into init.coffee.

require 'sugar' # some nice convenience methods

# 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 = (sprout, done) ->
  console.log 'welcome! this is my before message'
  done()

# 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 flatiron/prompt, found here:
# https://github.com/flatiron/prompt#valid-property-settings
exports.configure = [
  'name',
  'github_url',
  { name: 'travis'
    description: 'Do you want travis in this project?'
    type: 'boolean' }
]

# This function is executed after the configuration info is collected.
# 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 = (sprout, done) ->
  console.log sprout.config # all the config values you collected
  console.log sprout.files # list of files that will be copied

  if not sprout.config.travis then sprout.files.remove('.travis.yml')

  done(sprout)

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 : )