generate

Fast, composable, highly extendable project generator with a user-friendly and expressive API.

• Getting started
  • Install
• Usage
• CLI
• API
• Task API
• File System API
• Authoring generators
  • Generator naming conventions
• TODO
• Why Generate?
• License

(TOC generated by verb using markdown-toc)

Generate is a fast, well-tested (more than 1,000 unit tests), and highly pluggable project generator for node.js.

Feature highlights

• Generators can have gulp-style "tasks" (gulp plugins can be used too)
• Supports sub-generators, with any level of nesting!
• Generators can extend and use other generators
• Generators, sub-generators and their tasks can be run by command line or API
• Generate can be used as a node.js library, to add generate's functionality to other applications (for example, generate is used in assemble)

Getting started

Install

To get started, you'll first need to install generate globally using npm, along with any generators you'd like to run.

Install Generate

Install globally with npm

$ npm i -g generate

Usage

$ gen <command> [args]

CLI

(WIP)

help

(TODO)

Get started with Generate.

$ gen help

init

(TODO)

Get started with Generate.

$ gen init

Upon running init, generate will prompt you for answers to the following questions:

Run generators

$ gen <generator name> [options]

Example

Run generator abc

$ gen abc

Run tasks

To run a task on the base generator, just pass the name of the task to run.

$ gen <task name> [options]

Unless overridden by the user, the base generator is the default generator that ships with Generate. This generator doesn't really "generate" anything, but it will prompt you for a few answers (if you choose), to store data that's commonly needed by templates, like author.name, GitHub username, etc.

Example

Run task bar:

$ gen bar

Run sub-generators

Sub-generators are normal generators that are called from (or registered by) other generators.

Dot-notation is used for getting and runing sub-generators.

$ gen <generator name>.<sub-generator name> [options]

Examples

Run sub-generator b on generator a:

$ gen a.b [options]

Run sub-generator c:

$ gen a.b.c [options]

And so on...

Run a generator's tasks

$ gen <generator name>:<task name> [options]

Example

Run task bar on generator foo.

$ gen foo:bar 

Run a sub-generator's tasks

$ gen <generator name>.<sub-generator name>:<task name> [options]

Example

Run task foo on sub.generator a.b.c.

$ gen a.b.c:foo 

API

{%= apidocs("index.js") %}

Task API

.task

Register a new task with it's options and dependencies. To return the task object of an already registered task, pass the name of the task without any additional parameters.

Params

• name {String}: Name of the task to register
• options {Object}: Options to set dependencies or control flow.
• options.deps {Object}: array of dependencies
• options.flow {Object}: How this task will be executed with it's dependencies (series, parallel, settleSeries, settleParallel)
• deps {String|Array|Function}: Additional dependencies for this task.
• fn {Function}: Final function is the task to register.
• returns {Object}: Return the instance for chaining

Example

// register task "site" with composer
app.task('site', ['styles'], function() {
  return app.src('templates/pages/*.hbs')
    .pipe(app.dest('_gh_pages'));
});

// get the "site" task object
var task = app.task('site');

.build

Build a task or array of tasks.

Params

• tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions.
• cb {Function}: Callback function to be called when all tasks are finished building.

Example

app.build('default', function(err, results) {
  if (err) return console.error(err);
  console.log(results);
});

.series

Compose task or list of tasks into a single function that runs the tasks in series.

Params

• tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions.
• returns {Function}: Composed function that may take a callback function.

Example

app.task('foo', function(done) {
  console.log('this is foo');
  done();
});

var fn = app.series('foo', function bar(done) {
  console.log('this is bar');
  done();
});

fn(function(err) {
  if (err) return console.error(err);
  console.log('done');
});
//=> this is foo
//=> this is bar
//=> done

.parallel

Compose task or list of tasks into a single function that runs the tasks in parallel.

Params

• tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions.
• returns {Function}: Composed function that may take a callback function.

Example

app.task('foo', function(done) {
  setTimeout(function() {
    console.log('this is foo');
    done();
  }, 500);
});

var fn = app.parallel('foo', function bar(done) {
  console.log('this is bar');
  done();
});

fn(function(err) {
  if (err) return console.error(err);
  console.log('done');
});
//=> this is bar
//=> this is foo
//=> done

.watch

Watch a file, directory, or glob pattern for changes and build a task or list of tasks when changes are made. Watch is powered by [chokidar][] so arguments can be anything supported by chokidar.watch.

Params

• glob {String|Array}: Filename, Directory name, or glob pattern to watch
• options {Object}: Additional options to be passed to [chokidar][]
• tasks {String|Array|Function}: Tasks that are passed to .build when files in the glob are changed.
• returns {Object}: Returns an instance of FSWatcher from [chokidar][]

Example

var watcher = app.watch('templates/pages/*.hbs', ['site']);

File System API

.copy

Copy files with the given glob patterns to the specified dest.

Params

• patterns {String|Array}: Glob patterns of files to copy.
• dest {String|Function}: Desination directory.
• returns {Stream}: Stream, to continue processing if necessary.

Example

app.task('assets', function(cb) {
  app.copy('assets/**', 'dist/')
    .on('error', cb)
    .on('finish', cb)
});

.src

Glob patterns or filepaths to source files.

Params

• glob {String|Array}: Glob patterns or file paths to source files.
• options {Object}: Options or locals to merge into the context and/or pass to src plugins

Example

app.src('src/*.hbs', {layout: 'default'});

.symlink

Glob patterns or paths for symlinks.

Params

• glob {String|Array}

Example

app.symlink('src/**');

.dest

Specify a destination for processed files.

Params

• dest {String|Function}: File path or rename function.
• options {Object}: Options and locals to pass to dest plugins

Example

app.dest('dist/');

Authoring generators

(TODO)

Generator naming conventions

Do

Use generate- as the prefix, followed by any words of your choosing to describe the purpose of the generator.

Don't

Use generator- as the prefix, since the word generator is already associated with yeoman.

TODO

• publish a fast, composable, highly extendable project generator with a user-friendly and expressive API
• support sub-generators (to any level of nesting)
• support streams, tasks, and plugins compatible with both gulp and assemble
• make it super easy to run specific tasks from any generator or sub-generator, programmatically or via CLI
• support instance plugins that allow you to easily add functionality and features to generate
• support any template engine
• support using any number of template engines at once, so that different file types can simultaneously be handled by the engine that was registered for that file type
• support templates as vinyl files, simple to use template collections and lists (for pagination, sorting, groups etc)
• support middleware that can be run on all files or specific files, and at specific points during the build process (like onLoad, preRender, postRender, etc)
• 1,000+ unit tests
• create and publish generators (we created a handful of generators that we've been using locally, these will be published shortly)
• CLI docs (started)
• User help (e.g. when the user does gen help or just gen)
• API docs
• Generator guidelines and conventions

Why Generate?

• Generate is an MIT licensed, open source project
• Generate was designed to be a faster, smarter, more extensible alternative to the current dominent solutions.
• Generate has an expressive, imperitive API. If you like gulp or express, you might like generate too.
• Generate is modular, and built on top of great libraries like bach, composer and assemble-core
• Generate is brought to you by @jonschlinkert and @doowb, whose projects - such as assemble and micromatch - are downloaded more than 200 million times a month.

Related projects

• assemble-core: The core assemble application with no presets or defaults. All configuration is left to the… more | homepage
• base-methods: base-methods is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… more | homepage
• base-resolver: 'base-methods' plugin for resolving and loading globally installed npm modules. | homepage
• base-runner: Orchestrate multiple instances of base-methods at once. | homepage
• resolve-modules: Resolves local and global npm modules that match specified patterns, and returns a configuration object… more | homepage

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016 Jon Schlinkert Released under the MIT license.

This file was generated by verb on January 09, 2016.