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/repositoryIf a version is specified, blu will install that specified tag version locally for future use.
blu install owner/repository v0.1.0Returns a list of all tags on the repository in GitHub.
blu tags owner/repositoryIf you are installing a template from a private repository, then this option will prompt for GitHub credentials.
blu authTo view all installed templates and versions, use the list command.
blu listTo 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/repositoryItems will be displayed for the specified template version (if installed).
blu items owner/repository v0.0.8blu 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/repositoryOnly removes the version (if it has been previously installed).
blu remove owner/repository v0.0.1blu 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
_supportanditems) - 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/repositoryblu create owner/repository v0.1.0Note: 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
_supportanditems) - 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 itemNameNote: the order is important - the version must come first if specified.
blu item owner/repository v0.1.0 itemName