blu
is an templating system that uses tagged GitHub repositories in order to generate projects. Project and item templates can include metadata and control files in order to provide features beyond simple file copying.
blu
works off of GitHub repositories that are tagged. A specific version for a template must be installed on the machine (blu
uses ~/.blu
) in order to create projects or items.
All files can use inline lodash
templates. The data required by these templates must be provided via a set of prompts. Code imports can be provided to the templates by including a .context.js
file that returns a hash containing the aliased libraries/functions required by the templates.
blu
supports both project templates (intended one-time use) and item templates (repeatable additions). Item templates get their own subdirectories under a _items
directory in the template.
blu
uses a .prompt.js
file to specify how to collect each template variable. Inquirer
is used to collect answers so the metadata provided by this file can take full advantage of its features.
blu
now supports two formats for what this module exports - a simple array of prompts and a hash that can specify prompts as well as before and after processors.
// a very simple template with only one variable would only need a single prompt
module.exports = [
{
name: 'projectName',
type: 'input',
message: 'Project name'
}
];
The before function should return a hash or a promise that resolves to one that will be passed down-stream.
The after function is passed the merged answers from the prompts and the result of the before call and should return a hash or a promise that resolves to one.
// this example won't change anything, it only demonstrates the format
module.exports = {
before: function() {
return {}; // well, that was boring
},
prompts: [
{
name: 'projectName',
type: 'input',
message: 'Project name'
}
],
after: function( answers ) {
return answers; // also boring
}
};
The optional '.context.js' file should return a hash with anything required by the templates that are not provided by the prompts.
// make environment variables available to the templates easily
module.exports = {
'environment': process.env
}
blu
allows more control over where template files are placed through an optional .structure.json
file. It provides a map of template files to a relative destination path that can contain template variables. The most common use case for this feature is for item templates.
Note: the key and value paths should be relative to the repository root.
{
"./sourceFile.js": "./src/things/${thingName}.js"
}
Given a value of "test1" for thingName
, a copy of sourceFile.js
would be saved to ./src/things/test1.js
after running it through lodash
's template function.
Before and after sets of shell commands can be specified using the optional '.commands.json'. To understanding all the features available in specifying these commands, see Drudgeon
's documentation.
Note: before and after commands refer to when the run relative to fulfilling the templates.
This example demonstrates before and after sets of tasks. The before will delete the local node_modules
folder (if it exists) and then install any pre-defined package dependencies in one step and then install another set of libraries as dependencies.
{
"before": {
"npm-clear": {
"cwd": "./",
"cmd": {
"win32": "rmdir",
"*": "rm"
},
"args": {
"win32": [ "./node_modules", "/s" ],
"*": [ "-rf", "./node_modules" ]
}
}
},
"after": {
"npm-libs": {
"cwd": "./",
"cmd": {
"win32": "npm.cmd",
"*": "npm"
},
"args": [ "install" ]
},
"npm-dependencies": {
"cwd": "./",
"cmd": {
"win32": "npm.cmd",
"*": "npm"
},
"args": [ "install", "autohost", "hyped", "when", "lodash", "fount", "-S" ]
}
}
}
Because the .prompts.js
and .context.js
files can make use of custom code, you can store detailed support functionality under a _support
folder to require into either of these files that will not be copied during project creation.
You can define NPM dependencies for your template in this file. The format is the same as the "dependencies"
block in a package.json
file:
{
"lodash": "~3.9.1",
"when": "^3.7.3"
}
If you want to include a package.json file that blu will template for you, you'll need to place it in the _support
directory. Failing to remember this will cause your templates to break.
Installs a template from a GitHub repository.
If no version is specified, blu
will take the latest tag based on semver.
blu install owner/repository
If a version is specified, blu
will install that specified tag version locally for future use.
blu install owner/repository v0.1.0
Returns a list of all tags on the repository in GitHub.
blu tags owner/repository
If you are installing a template from a private repository, then this option will prompt for GitHub credentials.
blu auth
To view all installed templates and versions, use the list command.
blu list
To see what item templates are part of a particular project, use the items command to get the list.
Items will be displayed for the latest version of the installed template if no version is specified.
blu items owner/repository
Items will be displayed for the specified template version (if installed).
blu items owner/repository v0.0.8
blu
allows both removing all installed template versions as well as targeted installed versions.
If no version is provided, all installed versions are removed for the repository.
blu remove owner/repository
Only removes the version (if it has been previously installed).
blu remove owner/repository v0.0.1
blu
creates project and item templates in the current working directory. Please use caution when using the create
and item
commands.
Creating a project from an installed template will:
- run the before steps (if they exist)
- collect data from user via prompts
- expand templates (ignores anything under
_support
anditems
) - run the after steps (if they exist)
Without specifying a version, blu
will use the latest installed version based on semantic version comparison of the installed tags.
blu create owner/repository
blu create owner/repository v0.1.0
Note: only metadata/control files found under the item's template folder get used during item creation.
Adding an item from a project does the following:
- run the before steps (if they exist)
- collect data from user via prompts
- expand templates in the item's folder (ignores anything under
_support
anditems
) - run the after steps (if they exist)
Without specifying a version, blu
will use the latest installed version based on semantic version comparison of the installed tags.
blu item owner/repository itemName
Note: the order is important - the version must come first if specified.
blu item owner/repository v0.1.0 itemName