node package manager

generate

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.

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.

generate

You might also be interested in update.

Get in touch!

Have questions, suggestions, or want to discuss generate? Join the conversation on gitter or give us a shout on twitter. The generate team and community are always happy to help!

Interested in seeing how generate works first-hand before reading another line? See the quickstart instructions.

(TOC generated by verb using markdown-toc)

Generate is a developer tool for rapidly generating files, code snippets, and even complete projects by using templates, answers to prompts, stored preferences, user environment and so on.

Generators

All of the actual "generating" is accomplished using plugins called generators, which can be run by command line or using Generate's API.

The project you are currently visiting is Generate's core codebase, which provides the command line tool and API for creating, resolving, registering, and running "generators".

Visit the docs to learn more about Generate or generators.

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

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

  • 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.
  • macros: create a completely custom generator from the command line using macros.
  • 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 alongside the following libraries as part of a build workflow:

Additionally, all of these applications are built on top of base and templates.

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 a "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

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.

With macros you can create a completely custom generator, or generator experience, from the command line.

Example

The following will create macro foo with the arguments project:minimal travis editorconfig:

$ gen --macro foo project:minimal travis editorconfig

Now, you can simly run $ gen foo instead of $ gen project:minimal travis editorconfig.

How do macros work?

When the --macro flag is used, the process.argv array that was passed with the macro (excluding the --macro flag itself and the macro name) is persisted to a macro-store. The next time macro name is used as a command line argument, the stored argv array is returned instead.

See macro-store for more details.

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

  • --dest, -d: Set the destination directory to use for generated files.
  • --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.

  • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… 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

Changelog entries are classified using the following labels (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
  • bumped: updated dependencies, only minor or higher will be listed.

0.13.0 - 2016-10-01

Fixed

  • improve answer handling in ask listener
  • update dependencies

0.12.1 - 2016-09-18

Fixed

  • Ensure cwd is set and dest is set on app.cache.data
  • Ensure the reverse of a negative flag is set on options

0.12.0 - 2016-09-12

Added

0.11.0 - 2016-08-17

Fixed

  • CLI: macro handling was improved

Removed

  • Unused app.paths property

Bumped

0.10.0 - 2016-08-09

Changed

  • More improvements to user-defined template handling.
  • Documentation

0.9.0 - 2016-07-12

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.

Are you using Generate in your project? Have you published a generator and want to share your project with the world?

Here are some suggestions!

  • If you get like Generate and want to tweet about it, please feel free to mention @generatejs or use the #generatejs hashtag
  • Show your love by starring Generate and generate
  • Get implementation help on StackOverflow (please use the generatejs 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 generategenerator 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

Jon Schlinkert

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


This file was generated by verb-generate-readme, v0.1.31, on October 01, 2016.