Generator Core Library

This is the core library of the project generators.

Getting Started

Clone this repository and set up a link to it. In the project from which you intend to use the library, execute:-

npm install <path_to_generator_core>

TBD - replace with npm instructions when published.

Import the API functions from the library - see API documentation below.

import * as genlib from '@mcqj/npm-generator-lib`;

Overview

This library contains a set of utilities that can be used to write CLI generators that generate new projects from templates. The templates are written using a template language. Most of our examples use Embedded Javascript (EJS) but other templating languages are supported (e.g. nunjucks).

Generally, you will create a set of templates in a folder structure that will be replicated in the generated project. The files in those folders are treated as templated files and are processed by the chosen templating engine, with the output being written to the target project. We only support a single templating engine for a given project.

In the most basic workflow, your CLI program will call getTemplateVars to prompt the user for parameter values that will be used to customise the templates. Then it will call copyTemplateFiles to create the target project. There are a number of other optional calls that are documented in the API section.

API

getTemplateVars(optionsDescriptor)

optionsDescriptor is an object that describes the parameters that we wish to obtain from the command line. The parameters may come from one of two sources

• a CLI option e.g. <generatorName> -u username
• a saved value from a previous run of the generator
• an option obtained from the user by prompting for input

optionsDescriptor is an object where the property keys correspond to the values that you wish to obtain from the different possible sources outline above. The property values are:-

• type - required the type of this property e.g. 'string'.
• short- optional the short value that can be used when specifying the command line option
• placeholder - optional used as a placeholder for the value when displaying a help message
• message - optional the prompt message to be displayed when prompting the user

Example optionsDescriptor:-

const optionsDescriptor = {
  region: {
    type: 'string',
    short: 'r',
    placeholder: 'region',
    message: 'The AWS region where the project will be deployed (e.g. "eu-west-1"):',
  },
  prefix: {
    type: 'string',
    short: 'p',
    placeholder: 'prefix',
    message: 'Project prefix (Typically the name of the product being built):',
  },
  stagesList: {
    type: 'string',
    short: 's',
    placeholder: 'stages',
    message: 'The deployment stages (comma separated list e.g. "dev, prod"):',
  },
  domain_name: {
    type: 'string',
    short: 'd',
    placeholder: 'domain name',
    message: 'Domain name:',
  },
};```

Returns a promise that resolves to an object containing the user's template variables.

createProject(projectName)

projectName is the name of the project as a string. It is assumed that the project will be created in a direct sub-folder of the current folder where the CLI is running.

Returns a promise that resolves to projectRoot.

saveDefaultVars(templateVars)

Saves template variables to a file in the user's home folder. The file is saved as .gencore/defaultParams.json in the user's home folder.

templateVars is an object containing the template variables to be saved.

Returns a promise that resolves when the template vars have been successfully saved.

getDefaultVars()

Gets saved template variables from a file. See saveDefaultVars.

Returns a promise that resolves to a templateVars object or that rejects if it cannot find a valid templateVars JSON file.

reverseDomain(domain)

Takes a domain name as a string and reverses it.

domain is the string containing the domain name that is to be reverses.

Returns the reversed domain name.

copyTemplateFiles(params)

Recursively copies files from the template folder to the new project.

The params object has the following properties:-

• templateRoot - required is a string containing the path to the template folder that contains the template files used to populate the new project. The templates are passed through the configured template language processor, where template placeholders are replaced, using the parameters supplied by the user
• projectRoot - required is a string containing the path to the root folder of the new project, where the transformed files are saved.
• templateVars - optional is an object containing the template variables to be used by the template processor plugin. The object's keys are the names of the placeholders to be replaced in the templates and the values are the values to be inserted.
• stageNamePlaceholder - optional is a string containing a name that is used to identify a folder / file that will be replicated multiple times based on the stage names.
• stageNames - optional (required if stagNamePlaceholder is provided) is an array of strings with the stage names to be generated. A file / folder will be created for each stage name and the template files will be processed for each stage.
• renameFiles - optional an object containing the file names to be renamed. The object's keys are the names of the files to be renamed and the values are the new names to be used. This can be particularly useful in overcoming the fact that npm install will not install .gitgnore files. If you want to have a .gitignore file in your template, you use an alternative name e.g gitignore and use this field to have it renamed to .gitignore in the target project.
• patterns - optional An array of glob patterns to match files against and a transformer to use for files matching each pattern. The null template processor is the default and will be used for files that do not match any of the patterns. If no patterns are provided, the null template processor will be used for all files, resulting in all files being copied without processing.

It is quite common that we will want to generate projects that will have multiple stages as determined by the user at creation time (e.g. dev, staging, prod). In order to support that scenario, we support the use of a special folder/file name in the template, that will be passed through the template processor multiple times to generate multiple output folders and/or files with different names.