Skip to content

Latest commit

 

History

History
166 lines (110 loc) · 6.47 KB

.verb.md

File metadata and controls

166 lines (110 loc) · 6.47 KB
Raw

Table of contents

Why use Generate?

Why use Generate?

There are other project scaffolders out there, why should you spend your time learning to use Generate?

Generate offers the robustness, power and configurability of Yeoman, with the expressiveness and simplicity of [slush][] and [gulp][]. See the following links if you're interested in a more detailed comparison:

Features

Features

  • advanced flow control: through the use of generators (not es2015 generators), sub-generators, and tasks
  • render templates: use templates to create new files, or replace existing files
  • any engine: use any template engine to render templates, including [handlebars][], [lodash][], [swig][] and [pug][], and anything supported by [consolidate][]. This is useful for generating templates from templates.
  • data: automatically gather data from the user's environment for rendering templates, to populate "hints" in user prompts or for rendering templates, etc.
  • prompts: It's easy to create custom prompts and use the answers for: context for rendering templates, settings options, determining file names, directory structure, and anything else that requires user feedback.
  • macros: create a completely custom generator from the command line using macros.
  • front-matter: use yaml front matter in templates to define settings or defaults on a file-by-file basis
  • smart plugins: Update is built on [base][], so any "smart" plugin from the Base ecosystem can be used
  • config store: persist configuration settings, global defaults, project-specific defaults, answers to prompts, and so on.
  • streams: full support for [gulp][] and [assemble][] plugins
  • vinyl: files and templates are [vinyl][] files.
  • much more!
Developer toolkit

Developer toolkit

Generate is part of a suite of developer tools that share a common foundation. Any of these tools may be used standalone or together:

  • [generate][]: (you are here) scaffold out new projects
  • [assemble][]: build system for web projects
  • [verb][]: documentation system for code projects
  • [update][]: automate updates of any kind in code projects

All of these applications are built on top of [base][] and [templates][], which provides a number of benefits, including:

  • similar API/CLI - Learn one, and you will know them all
  • common plugins - create a plugin for one, it will be usable by the others
  • cross-compatible - they can run one another (for example, assemble can run verb to generate markdown documentation, then use that to create an HTML website)

Command line usage

Generate may be installed locally or globally. However, if you wish to run any globally installed generators, Generate's CLI must be installed globally as well.

Install Generate

Install generate globally using npm:

$ npm install --global generate

This adds the gen command to your system path, allowing it to be run from anywhere.

Install a generator

If you'd like to see how generators work, install generate-example:

$ npm install --global generate-example

Then run the example generator with the following command:

$ gen example

Visit the [generate-example][] project for additional steps and guidance.

Next steps

Command line arguments

The syntax for running generators is:

$ gen generator:task
  • generator one or more space-separated generator names
  • task - (optional) one or more comma-separated task names

Examples

# run generate-project's "default" task
$ gen project
# run generate-project's "license" task
$ gen project:license
# run generate-project's "package" task
$ gen project:package

generator.js

If a generator.js is in the current working directory, Generate's CLI will attempt to load it and execute any tasks you've specified at the command line.

Examples

Generators

generators are plugins that can be run by command line or using Generate's API.

Discovering generators

  • Find generators to install by searching npm for packages with the keyword generategenerator
  • Visit Generate's GitHub org to see the generators maintained by the core team

Discovering plugins

Plugins from any applications built on [base][] should work with Generate (and can be used in your generator):

  • base: find base plugins on npm using the baseplugin keyword
  • assemble: find assemble plugins on npm using the assembleplugin keyword
  • generate: find generate plugins on npm using the generateplugin keyword
  • templates: find templates plugins on npm using the templatesplugin keyword
  • update: find update plugins on npm using the updateplugin keyword
  • verb: find verb plugins on npm using the verbplugin keyword

Authoring generators

Visit the documentation for generators to learn how to use, author and publish generators.

More information