Simple new project templating
Note: This project is in early development, and versioning is a little different. Read this for more details.
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.
npm install sprout -g
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.
Command:
sprout add [name] <clone_url_or_path>
Description: Adds a template to your repertoire. Name represents how you would like the template to be named within sprout. You are required to add a template which can be either a clone url or a path to a local template. If no name is provided, sprout will use the last piece of the template as the name.
Command:
sprout remove <name>
Description: Removes the template with the specified name from sprout.
Aliases: rm, delete
Command:
sprout list
Description: Lists all templates that you have added to sprout.
Aliases: ls, all
Command:
sprout init <name> [path] [overrides]
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.
Options: You can pass override arguments like -o key value key2 val2 as options which will override the prompts set in your templates.
Aliases: new, create
Note: Options overrides set from the command line will only be passed to your ejs templates as either a string or a boolean. This means that when overriding there are many powerful features from inquirer.js (like validation) that you won't be able to take advantage of.
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) Example code given in coffeescript:
path = require 'path'
sprout = require 'sprout'
# Adding a template
# -----------------
sprout.add({ name: 'node', uri: 'https://github.com/carrot/sprout-node' })
.catch(console.error.bind(console))
.done(-> console.log('template added!'))
# removing a template
# -------------------
sprout.remove('node')
.catch(console.error.bind(console))
.done(-> 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({
name: 'node',
path: path.join(process.cwd(), 'new_project'),
overrides: { foo: 'bar' } # optional, will prompt if not provided
defaults: { name: 'suggested name'} # optional
}).catch(console.error.bind(console))
.done(-> console.log('project 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')
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.
# 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 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.
# 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_values # all the config values you collected
if not sprout.config_values.travis then sprout.remove('.travis.yml')
done()
We also provide you the power of String.js in all of your ejs templates. This means you can run powerful string operations on your user input like:
class <%= S('user_model').capialize().s; %> // given 'user_model' is prompted by your init.coffeeSo 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 : )