generate-package

generate-package

Generate a package.json from a pre-defined or user-defined template. This generator can be used from the command line when globally installed, or as a plugin or sub-generator in your own generator.


Table of Contents

• What is "Generate"?
• Command line usage
  • Install
  • Run
  • Help
  • Options
  • Running tasks
• Available tasks
• Running multiple generators
  • generate-dest
• API usage
  • Install locally
  • Use as a plugin
  • Register as a generator
• Customization
  • Destination directory
  • Overriding templates
• About
  • Related projects
  • Contributing
  • Running tests
  • Author
  • License

(TOC generated by verb using markdown-toc)

What is "Generate"?

Generate is a command line tool and developer framework for scaffolding out new GitHub projects using generators and tasks.

Answers to prompts and the user's environment can be used to determine the templates, directories, files and contents to build. Support for gulp, base and assemble plugins, and much more.

For more information:

• Visit the generate project
• Visit the generate documentation
• Find generators on npm (help us author generators)

Command line usage

Install

Installing the CLI

To run the package generator from the command line, you'll need to install Generate globally first. 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 any directory.

Install generate-package

Install this module with the following command:

$ npm install --global generate-package

Run

You should now be able to run generate-package with the following command:

$ gen package

What will happen?

Running $ gen package will run the generator's default task, which will:

• prompt you to choose a license to generate
• prompt you for any information that's missing, if applicable (like author name, etc.)
• render the necessary template(s) using your answers
• write the resulting file(s) to the current working directory

Conflict detection

This generator will prompt you for feedback before overwrite existing files. You can set the destination to a new directory if you want to avoid the prompts, or avoid accidentally overwriting files with unintentional answers => 'Oops! I meant "no! Don't overwrite!!!"'.

What you should see in the terminal

If completed successfully, you should see both starting and finished events in the terminal, like the following:

[00:44:21] starting ...
...
[00:44:22] finished ✔

If you do not see one or both of those events, please let us know about it.

Help

To see a general help menu and available commands for Generate's CLI, run:

$ gen help

Options

• --dest, -d: set the destination directory to use for generated files
• --no-hints: Don't use hints in prompts (except for global data, like author.name)

Running tasks

Generators use tasks for flow control. Tasks are run by passing the name of the task to run after the generator name, delimited by a comma.

Example

For instance, the following will run generator foo, task bar:

$ gen foo:bar
       ^       ^
generator     task

Default task

When a task name is not explicitly passed on the command line, Generate's CLI will run the default task.

Available tasks

package:new

Create a new package.json file, same as the raw task, but also normalizes the result using normalize-pkg.

Example

$ gen package:new

package:raw

Generate a package.json file in the cwd. To use a different template, run the package:choose task, or pass the name on the -t or --template flag.

Example

$ gen package:raw

package:dev

Generate a temporary package.json file in the cwd for dev, tests, etc. All of the fields in this file are pre-populated with bogus data.

Example

$ gen package:dev

package:choose

Prompts the user to choose the template to use for generating a package.json file to the working directory, or specified -d | --dest.

Example

$ gen package:choose

package:package-hints

Merge data to be used for hints onto the context.

Example

$ gen package:package-hints

Visit Generate's documentation for tasks.

Running multiple generators

Generate supports running multiple generators at once. The following generator(s) work well with generate-package:

generate-dest

Run generate-dest before generate-package to prompt for the destination directory to use for generated files.

$ gen dest package

Example

API usage

Use generate-package as a plugin in your own generator.

Install locally

Install with npm:

$ npm install --save generate-package

Use as a plugin

When used as a plugin, tasks from generate-package are added to your generator's instance.

module.exports = function(app) {
  app.use(require('generate-package'));
  // do generator stuff
};

Running tasks

You can now run any tasks from generate-package as if they were part of your own generator.

module.exports = function(app) {
  app.use(require('generate-package'));

  app.task('foo', function(cb) {
    // do task stuff
    cb();
  });

  // run the `mit` task from `generate-package`
  app.task('default', ['foo', 'mit']);
};

Register as a generator

When registered as a generator, tasks from generate-package are added to the "namespace" you give to the generator.

module.exports = function(app) {
  app.register('foo', require('generate-package'));
  // generate
};

Running tasks

Pass the names of one or more tasks to run to the .generate method, prefixed with the namespace of the sub-generator (foo, in our example):

Examples

Run the bar task from generator foo:

module.exports = function(app) {
  app.register('foo', require('generate-package'));

  app.generate('foo:bar', function(err) {
    if (err) console.log(err);
  });
};

Wrap the call to .generate in a task, so it can be run on demand:

module.exports = function(app) {
  app.register('foo', require('generate-package'));

  app.task('bar', function(cb) {
    app.generate('foo:bar', cb);
  });
};

More information

Visit the generator docs to learn more about creating, installing, using and publishing generators.

Customization

The following instructions can be used to override settings in generate-package. Visit the Generate documentation to learn about other ways to override defaults.

Destination directory

To customize the destination directory, install generate-dest globally, then in the command line prefix dest before any other generator names.

For example, the following will prompt you for the destination path to use, then pass the result to generate-package:

$ gen dest package

Overriding templates

You can override a template by adding a template of the same name to the templates directory in user home.

For example, to override the foo.tmpl template, add a template at the following path ~/generate/templates/foo.tmpl, where ~/ is the user-home directory that os.homedir() resolves to on your system.

About

Related projects

• generate-gitignore: Generate a .gitignore file from the command line when Generate's CLI is installed globally, or… more | homepage
• generate-license: Generate a license file for a GitHub project. | homepage
• generate-readme: Generate a README.md using answers to prompts and data from the environment, like package.json, .git… [more](https://github.com/generate/generate-readme) | [homepage](https://github.com/generate/generate-readme "Generate a README.md using answers to prompts and data from the environment, likepackage.json,.git` config, etc. This generator can be run by command line if Generate is installed globally, or you can use this as a plugin or sub-generator in your own")

Contributing

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

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

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

This file was generated by verb-generate-readme, v0.1.29, on August 09, 2016.