Generator (args, options, features)

The Generator class provides the common API shared by all generators. It define options, arguments, file, prompt, log, API, etc.

It mixes into its prototype all the methods found in the actions/ mixins.

Every generator should extend this base class.

new Generator (args, options, features)

Parameters:
Name Type Description
args Array.<string>

Provide arguments at initialization

options Object

Provide options at initialization

Properties
Name Type Attributes Description
customPriorities Array.< Priority > <optional>

Custom priorities

features Object

Provide Generator features information

Properties:
Name Type Description
env Object

the current Environment being run

resolved String

the path to the current generator

description String

Used in --help output

appname String

The application name

config Storage

.yo-rc config file manager

fs Object

An instance of Mem-fs-editor

log function

Output content through Interface Adapter

uniqueBy String

The Generator instance unique identifier. The Environment will ignore duplicated identifiers.

unique String

uniqueBy calculation method (undefined/argument/namespace)

tasksMatchingPriority boolean

Only queue methods that matches a priority.

taskPrefix String

Tasks methods starts with prefix. Allows api methods (non tasks) without prefix.

customInstallTask boolean | function

Provides a custom install task. Environment >= 3.2.0 Environment built-in task will not be executed

customCommitTask boolean | function

Provides a custom commit task. Environment >= 3.2.0 Environment built-in task will not be executed

Mixes In:
Example
const Generator = require('yeoman-generator');
module.exports = class extends Generator {
  writing() {
    this.fs.write(this.destinationPath('index.js'), 'const foo = 1;');
  }
};

Extends

Members

config

Generator config Storage.

packageJson

Package.json Storage resolved to this.destinationPath('package.json') .

Environment watches for package.json changes at this.env.cwd , and triggers an package manager install if it has been committed to disk. If package.json is at a different folder, like a changed generator root, propagate it to the Environment like this.env.cwd = this.destinationPath() .

Example
this.packageJson.merge({
  scripts: {
    start: 'webpack --serve',
  },
  dependencies: {
    ...
  },
  peerDependencies: {
    ...
  },
});

Methods

_templateData (path) → {Object}

Utility method to get a formatted data for templates.

Parameters:
Name Type Description
path String

path to the storage key.

Returns:
Object -

data to be passed to the templates.

Mixes In:

async addDependencies (dependencies) → {Promise}

Add dependencies to the destination the package.json.

Environment watches for package.json changes at this.env.cwd , and triggers an package manager install if it has been committed to disk. If package.json is at a different folder, like a changed generator root, propagate it to the Environment like this.env.cwd = this.destinationPath() .

Parameters:
Name Type Description
dependencies Object | string | Array.<string>
Returns:
Promise -

a 'packageName: packageVersion' object

Inherited From:

async addDevDependencies (dependencies) → {Promise}

Add dependencies to the destination the package.json.

Environment watches for package.json changes at this.env.cwd , and triggers an package manager install if it has been committed to disk. If package.json is at a different folder, like a changed generator root, propagate it to the Environment like this.env.cwd = this.destinationPath() .

Parameters:
Name Type Description
dependencies Object | string | Array.<string>
Returns:
Promise -

a 'packageName: packageVersion' object

Inherited From:

argument (name, config) → {this}

Adds an argument to the class and creates an attribute getter for it.

Arguments are different from options in several aspects. The first one is how they are parsed from the command line, arguments are retrieved based on their position.

Besides, arguments are used inside your code as a property ( this.argument ), while options are all kept in a hash ( this.options ).

Parameters:
Name Type Description
name String

Argument name

config Object

Argument options

Properties
Name Type Attributes Description
type any

String, Number, Array, or Object

description string <optional>

Description for the argument

required boolean <optional>

required` Boolean whether it is required

optional boolean <optional>

Boolean whether it is optional

default any <optional>

Default value for this argument

Returns:
this -

This generator

argumentsHelp () → {String}

Get help text for arguments

Returns:
String -

Text of options in formatted table

Mixes In:

cancelCancellableTasks ()

Ignore cancellable tasks.

composeWith (generator, args opt , options opt , immediately opt ) → { Generator }

Compose this generator with another one.

Parameters:
Name Type Attributes Default Description
generator String | Object | Array

The path to the generator module or an object (see examples)

args Array <optional>

Arguments passed to the Generator

options Object <optional>

The options passed to the Generator

immediately boolean <optional>
false

Boolean whether to queue the Generator immediately

Returns:
Generator -

The composed generator

Examples

Using a peerDependency generator

this.composeWith('bootstrap', { sass: true });

Using a direct dependency generator

this.composeWith(require.resolve('generator-bootstrap/app/main.js'), { sass: true });

Passing a Generator class

this.composeWith({ Generator: MyGenerator, path: '../generator-bootstrap/app/main.js' }, { sass: true });

copyDestination (from, to, …args) → {*}

Copy file from destination folder to another destination folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.copy(this.destinationPath(from), this.destinationPath(to)).

Parameters:
Name Type Attributes Description
from String

absolute file path or relative to destination folder.

to String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

copyTemplate (from, to, …args) → {*}

Copy file from templates folder to destination folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.copy(this.templatePath(from), this.destinationPath(to))

Parameters:
Name Type Attributes Description
from String

absolute file path or relative to templates folder.

to String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

copyTemplateAsync (from, to, …args) → {*}

Copy file from templates folder to destination folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.copy(this.templatePath(from), this.destinationPath(to))

Parameters:
Name Type Attributes Description
from String

absolute file path or relative to templates folder.

to String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

createStorage (storePath, path opt , options opt ) → { Storage }

Return a storage instance.

Parameters:
Name Type Attributes Description
storePath String

The path of the json file

path String <optional>

The name in which is stored inside the json

options boolean | Object <optional>

Treat path as an lodash path

Returns:
Storage -

json storage

debug (…args)

Convenience debug method

Parameters:
Name Type Attributes Description
args any <repeatable>

parameters to be passed to debug

deleteDestination (filepath, …args) → {*}

Delete file from destination folder mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.delete(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

desc (description)

Simple setter for custom description to append on help output.

Parameters:
Name Type Description
description String
Mixes In:

destinationPath (…dest) → {String}

Join a path to the destination root.

Parameters:
Name Type Attributes Description
dest String <repeatable>

path parts

Returns:
String -

joined path

destinationRoot (rootPath) → {String}

Change the generator destination root directory. This path is used to find storage, when using a file system helper method (like this.write and this.copy )

Parameters:
Name Type Description
rootPath String

new destination root path

Returns:
String -

destination root path

determineAppname () → {String}

Determines the name of the application.

First checks for name in bower.json. Then checks for name in package.json. Finally defaults to the name of the current directory.

Returns:
String -

The name of the application

git.email () → {String}

Retrieves user's email from Git in the global scope or the project scope (it'll take what Git will use in the current context)

Returns:
String -

configured git email or undefined

Mixes In:

existsDestination (filepath, …args) → {*}

Exists file on destination folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.exists(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

getFeatures () → {Object}

Specifications for Environment features.

Returns:
Object

help () → {String}

Tries to get the description from a USAGE file one folder above the source root otherwise uses a default description

Returns:
String -

Help message of the generator

Mixes In:

moveDestination (from, to) → {*}

Move file from destination folder to another destination folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.move(this.destinationPath(from), this.destinationPath(to)).

Parameters:
Name Type Description
from String

absolute file path or relative to destination folder.

to String

absolute file path or relative to destination folder.

Returns:
* -

for more information see mem-fs-editor

Mixes In:

git.name () → {String}

Retrieves user's name from Git in the global scope or the project scope (it'll take what Git will use in the current context)

Returns:
String -

configured git name or undefined

Mixes In:

option (name opt , config) → {this}

Adds an option to the set of generator expected options, only used to generate generator usage. By default, generators get all the cli options parsed by nopt as a this.options hash object.

Parameters:
Name Type Attributes Description
name String <optional>

Option name

config Object

Option options

Properties
Name Type Attributes Description
type any

Either Boolean, String or Number

description string <optional>

Description for the option

default any <optional>

Default value

alias any <optional>

Option name alias (example -h and --help`)

hide any <optional>

Boolean whether to hide from help

storage Storage <optional>

Storage to persist the option

Returns:
this -

This generator

optionsHelp () → {String}

Get help text for options

Returns:
String -

Text of options in formatted table

Mixes In:

prompt (questions, storage opt ) → {Promise}

Prompt user to answer questions. The signature of this method is the same as Inquirer.js

On top of the Inquirer.js API, you can provide a {store: true} property for every question descriptor. When set to true, Yeoman will store/fetch the user's answers as defaults.

Parameters:
Name Type Attributes Description
questions object | Array.<object>

Array of question descriptor objects. See Documentation

Properties
Name Type Attributes Description
storage Storage | String <optional>

Storage object or name (generator property) to be used by the question to store/fetch the response.

storage Storage | String <optional>

Storage object or name (generator property) to be used by default to store/fetch responses.

Returns:
Promise -

prompt promise

queueMethod (method:, methodName opt , queueName opt , reject opt )

Schedule methods on a run queue.

Parameters:
Name Type Attributes Description
method: function | Object

Method to be scheduled or object with function properties.

methodName String <optional>

Name of the method (task) to be scheduled.

queueName String <optional>

Name of the queue to be scheduled on.

reject function <optional>

Reject callback.

queueTask (task:)

Schedule tasks on a run queue.

Parameters:
Name Type Description
task: Task

Task to be queued.

queueTaskGroup (taskGroup:, taskOptions opt )

Schedule tasks from a group on a run queue.

Parameters:
Name Type Attributes Description
taskGroup: Object

Object containing tasks.

taskOptions TaskOptions <optional>

options.

queueTasks () → {Promise}

Queue generator tasks.

Returns:
Promise

queueTransformStream (streams) → {this}

Add a transform stream to the commit stream.

Most usually, these transform stream will be Gulp plugins.

Parameters:
Name Type Description
streams stream.Transform | Array.<stream.Transform>

An array of Transform stream or a single one.

Returns:
this -

This generator

readDestination (filepath, …args) → {*}

Read file from destination folder mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.read(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

readDestinationJSON (filepath, …args) → {*}

Read JSON file from destination folder mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.readJSON(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

readTemplate (filepath, …args) → {*}

Read file from templates folder. mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.read(this.templatePath(filepath))

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to templates folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

registerConfigPrompts (questions)

Register stored config prompts and optional option alternative.

Parameters:
Name Type Attributes Default Description
questions Inquirer | Array.<Inquirer>

Inquirer question or questions.

Properties
Name Type Attributes Description
exportOption Object | Boolean <optional>

Additional data to export this question as an option.

question.storage Storage | String <optional>
this.config

Storage to store the answers.

registerPriorities (priorities)

Register priorities for this generator

Parameters:
Name Type Description
priorities Array.<Object>

Priorities

Properties
Name Type Attributes Description
priorityName String

Priority name

before String <optional>

The new priority will be queued before the before priority. Required for new priorities.

queueName String <optional>

Name to be used at grouped-queue

edit boolean <optional>

Edit a priority

skip boolean <optional>

Queued manually only

args Array.<Object> | function <optional>

Arguments to pass to tasks

renderTemplate (source, destination opt , templateData opt , templateOptions opt , copyOptions opt )

Copy a template from templates folder to the destination.

Parameters:
Name Type Attributes Description
source String | Array

template file, absolute or relative to templatePath().

destination String | Array <optional>

destination, absolute or relative to destinationPath().

templateData Object <optional>

ejs data

templateOptions Object <optional>

ejs options

copyOptions Object <optional>

mem-fs-editor copy options

Mixes In:

renderTemplateAsync (source, destination opt , templateData opt , templateOptions opt , copyOptions opt )

Copy a template from templates folder to the destination.

Parameters:
Name Type Attributes Description
source String | Array

template file, absolute or relative to templatePath().

destination String | Array <optional>

destination, absolute or relative to destinationPath().

templateData Object <optional>

ejs data

templateOptions Object <optional>

ejs options

copyOptions Object <optional>

mem-fs-editor copy options

Mixes In:

renderTemplates (templates, templateData opt )

Copy templates from templates folder to the destination.

Parameters:
Name Type Attributes Description
templates Array

template file, absolute or relative to templatePath().

Properties
Name Type Attributes Description
when function <optional>

conditional if the template should be written. First argument is the templateData, second is the generator.

source String | Array

template file, absolute or relative to templatePath().

destination String | Array <optional>

destination, absolute or relative to destinationPath().

templateOptions Object <optional>

ejs options

copyOptions Object <optional>

mem-fs-editor copy options

templateData Object <optional>

ejs data

Mixes In:

renderTemplatesAsync (templates, templateData opt )

Copy templates from templates folder to the destination.

Parameters:
Name Type Attributes Description
templates Array

template file, absolute or relative to templatePath().

Properties
Name Type Attributes Description
when function <optional>

conditional if the template should be written. First argument is the templateData, second is the generator.

source String | Array

template file, absolute or relative to templatePath().

destination String | Array <optional>

destination, absolute or relative to destinationPath().

templateOptions Object <optional>

ejs options

copyOptions Object <optional>

mem-fs-editor copy options

templateData Object <optional>

ejs data

Mixes In:

rootGeneratorName () → {String}

Determine the root generator name (the one who's extending Generator).

Returns:
String -

The name of the root generator

rootGeneratorVersion () → {String}

Determine the root generator version (the one who's extending Generator).

Returns:
String -

The version of the root generator

run () → {Promise}

Runs the generator, scheduling prototype methods on a run queue. Method names will determine the order each method is run. Methods without special names will run in the default queue.

Any method named constructor and any methods prefixed by a _ won't be scheduled.

Returns:
Promise -

Resolved once the process finish

setFeatures (features)

Configure Generator behaviours.

Parameters:
Name Type Description
features Object
Properties
Name Type Attributes Description
unique boolean | string <optional>

Generates a uniqueBy id for the environment Accepts 'namespace' or 'true' for one instance by namespace Accepts 'argument' for one instance by namespace and 1 argument

sourceRoot (rootPath) → {String}

Change the generator source root directory. This path is used by multiples file system methods like ( this.read and this.copy )

Parameters:
Name Type Description
rootPath String

new source root path

Returns:
String -

source root path

spawnCommand (command, args, opt opt ) → {String}

Normalize a command across OS and spawn it (asynchronously).

Parameters:
Name Type Attributes Description
command String

program to execute

args Array

list of arguments to pass to the program

opt object <optional>

any cross-spawn options

Returns:
String -

spawned process reference

Mixes In:

spawnCommandSync (command, args, opt opt ) → {String}

Normalize a command across OS and spawn it (synchronously).

Parameters:
Name Type Attributes Description
command String

program to execute

args Array

list of arguments to pass to the program

opt object <optional>

any cross-spawn options

Returns:
String -

spawn.sync result

Mixes In:

startOver (options opt )

Start the generator again.

Parameters:
Name Type Attributes Description
options Object <optional>

options.

templatePath (…dest) → {String}

Join a path to the source root.

Parameters:
Name Type Attributes Description
dest String <repeatable>

path parts

Returns:
String -

joined path

usage () → {String}

Output usage information for this given generator, depending on its arguments or options

Returns:
String -

Usage information of the generator

Mixes In:

github.username () → {Promise}

Retrieves GitHub's username from the GitHub API

Returns:
Promise -

Resolved with the GitHub username or rejected if unable to get the information

Mixes In:

writeDestination (filepath, …args) → {*}

Write file to destination folder mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.write(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In:

writeDestinationJSON (filepath, …args) → {*}

Write json file to destination folder mem-fs-editor method's shortcut, for more information see mem-fs-editor . Shortcut for this.fs.writeJSON(this.destinationPath(filepath)).

Parameters:
Name Type Attributes Description
filepath String

absolute file path or relative to destination folder.

args * <repeatable>

for more information see mem-fs-editor

Returns:
* -

for more information see mem-fs-editor

Mixes In: