Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

package-json-to-readme Build Status

Generate a from package.json contents. Works with node and io.js.


Every project worth its salt has a README that answers (at least) the following questions:

  • What's it called?
  • What is it for?
  • How do I install it?
  • How do I use it?
  • How do I test it?
  • What is the license?

With npm modules, most of that info can be gleaned from properties in the package.json file: name, description, scripts.test, preferGlobal, etc. That's why package-json-to-readme exists. Use it to generate a decent boilerplate README, then iterate from there.


npm i -g package-json-to-readme


# Write to stdout
readme package.json

# Pipe output into a new file
readme package.json >

# Add a Travis badge
readme package.json --travis

# Run tests and add their output
readme package.json --tests

# Do it all
readme package.json --tests --travis >

# If your package has an or example.js file, it will be used to
# generate a usage section like this one.

# If your example.js has a require("./") statement, the relative path will be
# replaced with the package name.


npm install
npm test


  • github-url-to-object: Extract user, repo, and other interesting properties from GitHub URLs
  • hogan.js: A mustache compiler.
  • strip-ansi: Strip ANSI escape codes
  • sync-exec: Synchronous exec with status code support. Requires no external dependencies, no need for node-gyp compilations etc.
  • yargs: Light-weight option parsing with an argv hash. No optstrings attached.

Dev Dependencies

  • mocha: simple, flexible, fun test framework
  • nixt: Simple and powerful testing for command-line apps



See Also

  • readme-md-generator, a CLI that's able to read your environment (package.json, git config...) to suggest you default answers during the README creation process.
  • mos, a pluggable module that injects content into your markdown files via hidden JavaScript snippets.