@reuters-graphics/bluprint

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

  [e-mail]: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:

1. Exporting a personal access token as the environment variable GITHUB_TOKEN:

export GITHUB_TOKEN=<your personal access token>

2. 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.