Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the robustness and configurability of Yeoman, the expressiveness and simplicity of Slush, and more powerful flow control and composability than either.

You might also be interested in update.

• What is "Generate"?
  • Why Generate?
  • Features
  • Build workflow
• Command line usage
  • Getting started
  • init
  • Options
• Generators
  • Discovering generators
  • Discovering plugins
  • Authoring generators
• More information
• About
  • Related projects
  • Community
  • Contributing
  • Running tests
  • History
  • Author
  • License

(TOC generated by verb using markdown-toc)

Please read our contributing guide if you'd like to learn more about contributing to this project.

Generate itself is a command line tool and API for creating, resolving, registering, and running "generators". Along with methods for rendering tempalates, storing preferences, initiating user prompts, and so on. All actual "generating" is accomplished using plugins called generators, which are run by command line or API, and can be installed globally, locally, or exported as a function from a local generator.js.

Generators can be found and installed through npm, or you can create your own generators using Generate's API.

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

• Comparison to Yeoman and Slush
• Generator framework comparison table

• exceptional flow control: through the use of generators and tasks
• render templates: use templates to create new files, or replace existing files
• prompts: It's easy to create custom prompts, and aswers to prompts can be used as context for rendering templates, for settings options, determining file names, directory structure, and anything else that requires user feedback.
• any engine: use any template engine to render templates, including handlebars, lodash, swig and pug, and anything supported by consolidate.
• data: gather data from the user's environment for rendering templates, to populate "hints" in user prompts or for rendering templates, etc.
• fs: in the spirit of gulp, use .src and .dest to read and write globs of files.
• vinyl: files and templates are vinyl files
• streams: full support for gulp and assemble plugins
• smart plugins: Update is built on base, so any "smart" plugin from the Base ecosystem can be used
• stores: persist configuration settings, global defaults, project-specific defaults, answers to prompts, and so on.
• much more!

Generate can be used as a standalone library, but it can also be used as a part of a larger build workflow when used alongside the following libraries:

• assemble: build projects
• verb: document projects
• update: maintain projects

The following instructions are intended to provide a basic demonstration of how Generate works. Visit the links after this section for more information.

1. Install generate

To use Generate's CLI, it must first be installed globally using npm. You can do that now with the following command.

$ npm install --global generate

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

2. Install an "generator"

To see how generators work, install generate-example:

$ npm install --global generate-example

3. Run

Run the example generator with the following command:

$ gen example

This appends the string foo to the contents of example.txt. Visit the generate-example project for additional steps and guidance.

Next steps

• Browse the documentation
• Learn about generators
• Learn about the built-in generators
• Learn about authoring generators
• Learn about setting options in templates

Tell Generate's CLI to automatically run certain generators every time the gen command is given:

$ gen init

You can run this command whenever you want to generate your preferences, like after installing new generators.

$ gen help

  Usage: generate <command> [options]

  Command: generator or tasks to run

  Options:

    --config, -c      Save a configuration value to the `gen` object in package.json
    --cwd             Set or display the current working directory
    --data, -d        Define data. API equivalent of `app.data()`
    --disable         Disable an option. API equivalent of "app.disable('foo')"
    --enable          Enable an option. API equivalent of "app.enable('foo')"
    --global, -g      Save a global configuration value to use as a default
    --help, -h        Display this help menu
    --init, -i        Prompts for configuration values and stores the answers
    --option, -o      Define options. API equivalent of `app.option()`
    --run             Force tasks to run regardless of command line flags used
    --silent, -S      Silence all tasks and generators in the terminal
    --show <key>      Display the value of <key>
    --version, -V     Display the current version of generate
    --verbose, -v     Display all verbose logging messages

  Examples:

    # run generator "foo"
    $ gen foo

    # run task "bar" from generator "foo"
    $ gen foo:bar

    # run multiple tasks from generator "foo"
    $ gen foo:bar,baz,qux

    # run a sub-generator from generator "foo"
    $ gen foo.abc

    # run task "xyz" from sub-generator "foo.abc"
    $ gen foo.abc:xyz

    Generate attempts to automatically determine if "foo" is a task or generator.
    If there is a conflict, you can force generate to run generator "foo"
    by specifying its default task. Example: `$ gen foo:default`

Note that all command line options are preceded by --, or - for abbreviations. Only generator names or tasks can be used as commands (without -- or -).

• --no-install: Don't automatically install dependencies or devDependencies after generating files.
• --no-hints: Don't use hints in prompts

See options documentation.

• 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

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][update-plugin]: find update plugins on npm using the updateplugin keyword
• verb: find verb plugins on npm using the verbplugin keyword

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

• Documentation
• API documentation
• Generaters maintained by the core team

• assemble: Assemble is a powerful, extendable and easy to use static site generator for node.js. Used… more | homepage
• base: base is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… more | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Are you using Generate in your project? Have you published an generator and want to share your Generate project with the world? Here are some suggestions:

• If you get like Generate and want to tweet about it, please use the hashtag #generatejs
• Get implementation help on StackOverflow (please use the gen tag in questions)
• Gitter Discuss Generate with us on Gitter
• If you publish an generator, thank you! To make your project as discoverable as possible, please add the keyword generate-generator to package.json.

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

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

Install dev dependencies:

$ npm install -d && npm test

The following labels are used for identifying changes:

(from keep-a-changelog)

• added: for new features
• changed: for changes in existing functionality
• deprecated: for once-stable features removed in upcoming releases
• removed: for deprecated features removed in this release
• fixed: for any bug fixes

Changed

• User-defined templates should now be stored in ~/generate/templates instead of ~/templates

Added

• common-config will be used for storing user preferences. We haven't implemented any logic around this yet, but the common-config API is exposed on the app.common property, so you can begin using it in generators.

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb, v0.9.0, on July 12, 2016.