README
The simplest way to scaffold new projects from GitHub templates.
Why this?
Reusing good code is the easiest way to speed up your development time and share solid conventions across your team.
If you've used Yeoman or similar tools to build shareable templates, bluprint has a few advantages:
- It's far simpler for anyone on your team to create a template regardless of what language they're comfortable working in.
- Your bluprint actually looks like the boilerplate you'll start from, so it's easy to tell what your bluprint will do at a glance.
- bluprint's CLI pulls your template directly from GitHub, which means distributing your code is as easy as
git push
.
bluprint is designed to be a fast, accessible and highly composable tool to build out a library of reusable code.
What's it do?
A bluprint is any GitHub repository you want to use as a template to scaffold out a new project. Just adding a .bluprintrc
JSON file to the root of a repo makes it a bluprint.
Register bluprints you use regularly with the CLI.
When you start a new project, the CLI will download the latest tarball of your files from GituHub (public or private repos supported) and scaffold out your local directory. Then it will apply any custom actions defined in your .bluprintrc
to transform your files.
bluprint actions can do complex things like move or rename files and folders, execute shell commands, ask users for input, render files through a templating engine to customize them for each project and more.
bluprint parts let you split your template into segments that can help you keep files synced between projects already underway and your bluprint.
Quickstart
Install
yarn global add @reuters-graphics/bluprint
or
npm install -g @reuters-graphics/bluprint
This package supports the latest active versions of node.
Create a new bluprint
Creating a bluprint from existing code is as easy as adding a .bluprintrc
JSON file to the root of your project and pushing to GitHub.
Use the new
command to create your .bluprintrc
in the root of the project you'd like to templatize:
bluprint new
That creates your .bluprintrc
.
{
"bluprint": "^0.0.1",
"name": "My bluprint",
"category": "",
"actions": []
}
Add a category
if you like, which will be used in the CLI to group similar bluprints together.
actions
can be added to process your bluprint files after scaffolding your directory. Read more in Actions and check out the example bluprint to see what you can do.
Commit your project to GitHub with the .bluprintrc
file.
Add a bluprint to your CLI
To use your new bluprint, add it to your CLI using its GitHub repository.
bluprint add <github repo>
Your GitHub repo can be referenced using any of:
the URL
https://github.com/reuters-graphics/my-bluprint
the ssh connect string
git@github.com:reuters-graphics/my-bluprint.git
the GitHub user/project shortcut
reuters-graphics/my-bluprint
If your repository is private, you can make sure the CLI has permission to access it by either:
- Exporting a personal access token as the environment variable
GITHUB_TOKEN
:
export GITHUB_TOKEN=<your personal access token>
- Adding your personal access token directly to the CLI:
bluprint token <your token>
Using bluprints with the CLI
Create a fresh directory for your new project.
mkdir my-new-project
cd my-new-project
Scaffold your project from one of your bluprints:
bluprint start
The CLI will ask you to pick a bluprint and will guide you through providing any other information your bluprint needs to finish scaffolding your project.
You can also pass a GitHub repo containing a bluprint directly to this command:
bluprint start <github repo>
Remove a bluprint from your CLI
If you need to remove a bluprint from your CLI, you can:
bluprint remove
Cloning repos
You can also use the CLI to directly clone a GitHub repo:
bluprint clone <github repo>
You can clone any GitHub repo using this command, including private repos (with a GitHub personal access token), regardless of whether the repo has a .bluprintrc
config or not.
When using the clone command, all actions will be ignored in your .bluprintrc
.
CLI commands
bluprint [command]
Commands:
bluprint add [repo] Add a new bluprint to your CLI
bluprint clone <repo> Clone a repo with bluprint
bluprint new [name] Create a new .bluprintrc file
bluprint remove [bluprint] Remove a bluprint from your CLI
bluprint start [bluprint] Start a new project from a bluprint
bluprint token [accessToken] Add a GitHub personal access token to your CLI
Options:
--version Show version number
--help Show help
⚙️ Actions
Actions let you orchestrate complex transformations of your files after your repository is pulled down. Each action is an object added to the actions
array in your .bluprintrc
file.
You can define as many actions as you like and they will be run in sequence when anyone uses your bluprint.
{
"bluprint": "^0.0.1",
"name": "My bluprint",
"category": "",
"actions": [{
"action": "prompt"
// Runs first...
}, {
"action": "render"
// Runs second...
}, {
"action": "log"
// Runs last...
}]
}
Check out the example bluprint to see what you can do with actions.
Here are the actions the CLI currently supports:
execute
{
"action": "execute",
"cmds": [
["yarn"],
["git", ["init"]]
],
"silent": true
}
This action executes arbitrary commands.
cmds
are arrays passed as arguments to a synchronous child process.
In each array, the first item is a string representing the command. The second is an array passed to the command as arguments.
silent
is an optional boolean argument that when true will suppress the output of the child process.
log
{
"action": "log",
"msg": "Finished creating your project!"
}
This action logs messages to your bluprint's users.
msg
is a string.
The message is processed as a chalk tagged template literal so you can easily add a bit of color to your messages:
"Welcome to your {green new} project!"
You can also reference any context your users supplied in a previous prompt action using mustache template syntax:
"Scaffolded your new project named {{ projectName }}!"
move
{
"action": "move",
"paths": [
["from/", "to/"],
["moveme.md", "moved.md"]
],
}
This action lets you move or rename files or directories.
paths
is an array of arrays. Each inner array represents a move action. The first item in a move action represents the file or directory to be moved and the second, the destination. You can use the answers from a previous prompt action in the destination string with mustache template syntax:
["moveme/code.js", "{{ someAnswer }}/code.js"]
copy
{
"action": "copy",
"paths": [
["from/", "to/"],
["copyme.md", "copied.md"]
],
}
This action lets you copy files or directories.
paths
is an array of arrays. Each inner array represents a copy action. The first item in a copy action represents the file or directory to be copied and the second, the name of the copied file or directory. You can use the answers from a previous prompt action in the copied name string with mustache template syntax:
["copyme/code.js", "{{ someAnswer }}/code.js"]
prompt
{
"action": "prompt",
"questions": [{
"type": "text",
"name": "projectName",
"message": "What should we call this project?"
}],
}
This action lets you ask your users for more information that is then available to subsequent actions.
questions
is an array of prompts.js questions. The name of each question will be available in all actions that use templating syntax, like render, log, move and regexreplace.
regexreplace
{
"action": "regexreplace",
"files": [
"README.md"
],
"replace": [
["color", "colour"],
["([0-9]{2})\/([0-9]{2})\/([0-9]{4})", "$2.$1.$3", "g"]
]
}
This action allows you to make replacements in files using regular expressions. The files array is a list of files in which to replace text. The first item in each replace array is a regular expression string; the second, a replacement string, which can use regex capture groups; and, optionally, a third to override regex flags (defaults to gm
). You can also use the answers from a previous prompt action in the replacement string with mustache template syntax:
["^Name: .+