@reuters-graphics/bluprint
v0.6.7
Published
Dead-easy application scaffolding and CLI.
Downloads
76
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
[email protected]: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: .+$", "Name: {{ userName }}"]
remove
{
"action": "remove",
"paths": [
"dir/*",
"README.md"
],
}
This action removes files or directories.
paths
is an array of glob strings relative to the root of your project directory.
render
{
"action": "render",
"engine": "mustache",
"files": ["README.md"],
"questions": [],
"context": {
"copyrightYear": "2020"
}
}
This action overwrites files after passing them through a templating engine with custom context.
engine
is the templating engine to use. Can be either "mustache"
or "ejs"
.
files
is an array of files to pass through the templating engine.
questions
is an array of prompts.js questions. The name of each question will be available only in this action as context to your template.
context
is an object of any additional context to pass to your templates.
Remember, any answers to previous prompt actions are also available as context to your templates. See the docs on mustache and EJS for more information on using their templating syntax in your files.
There are also a few extra utility functions provided to your EJS and mustache templates from the string package: camelize
, capitalize
, dasherize
, humanize
, latinise
, slugify
, titleCase
and underscore
.
In EJS, you'd use them like:
<%= slugify(myVariable) %>
... and in mustache ...
{{#slugify}}{{myVariable}}{{/slugify}}
Default context
Some actions -- log
, move
, regexreplace
& render
-- are given default context variables you can use. These variables include:
year
: full year at runtime, e.g.,2022
month
: zero-padded month at runtime, e.g.,02
day
: zero-padded date at runtime, e.g.,07
dirname
: the name of the parent directory where bluprint is being executed at runtime, e.g.,my-project-folder
You use them in string replacement operations, like:
{
"action": "regexreplace",
"files": ["my-file.txt"],
"replace": [
["YYYY", "{{ year }}"],
["project-name", "{{ dirname }}"]
]
}
Conditioning actions on prompt values
All actions can be conditionally run based on the answer to a previous prompt by adding a condition
key to the action object:
[
{
"action": "prompt",
"questions": [{
"type": "text",
"name": "userName",
"message": "What's your name?"
}]
},
{
"action": "log",
"msg": "Hi, Jon!" ,
"condition": ["userName", "Jon"]
}
]
The first item in the array is the string object path of the prompt variable name you want to test, the second is the value it should be. Any action that fails a condition test will be skipped.
{
"condition": ["myPromptVar", "some value"]
}
You may also condition an action on multiple prompt values:
{
"condition": [
["myPromptVar", "some value"],
["myOtherVar", true]
]
}
📦 Parts
Sometimes it's handy to use just a part of your bluprint. For example, you might want to update a few files in a project to sync up with changes in the upstream bluprint.
Parts make it possible to give your users the option to overwrite some files in a project scaffolded by your bluprint. Just add a parts
object to your .bluprintrc
. Each key should be the name of a part. The value should be an array of glob strings matching the files in your project that belong to that part.
{
"bluprint": "^0.0.1",
"name": "My bluprint",
"category": "",
"actions": [],
"parts": {
"Config files": [
"config/*",
".tasksrc"
],
"JS components": [
"src/js/components/**/*",
"src/scss/component-styles/*"
]
}
}
Now, when a user uses your bluprint, they'll be asked if they want to use the whole bluprint or just a part. If they choose a part, files matching any glob will be copied into the project directory. Those that don't will simply be ignored.
If you need to, you can make any action conditional on the part a user chooses using the bluprintPart
context variable.
{
"condition": ["bluprintPart", "Config files"]
}
If you want to run an action only when the whole bluprint is used, you can test for null
:
{
"condition": ["bluprintPart", null]
}
Merge JSON files
You can add a mergeJson
flag to your .bluprintrc
to attempt to merge (using lodash) any existing JSON files with JSON files in a part that would overwrite them.
{
"bluprint": "^0.0.1",
"name": "My bluprint",
"category": "",
"actions": [],
"parts": {},
"mergeJson": true
}
Properties in the part's JSON file will take precedence over the existing file.
So say you have an existing package.json
like:
{
"dependencies": {
"react": "14.0",
"lodash": "3.0"
}
}
... and your bluprint is updated to React 16 and adds d3 to the dependencies. Running a part that includes package.json
with mergeJson
set to true would result in these dependencies:
{
"dependencies": {
"react": "16.0",
"lodash": "3.0",
"d3": "5.0"
}
}
Developing
See the developing doc.
Credits
The bluprint logo was created by MHD AZMI DWIPRANATA and is part of The Noun Project, available via creative commons license.