bahmutov / npm-module-checklist

Steps to check when starting, working and publishing a module to NPM

npm-module-checklist

Steps to check when starting, working and publishing a module to NPM

You can add the included CHECKLIST.md into your project, or copy it into your README.md; then check items off as you go. Use one of the two badges to let everyone know your module is solid.

[![badge 1](https://img.shields.io/badge/follows-npm%20checklist-brightgreen.svg)](CHECKLIST.md)
[![badge 2](https://img.shields.io/badge/%E2%98%B0-%E2%9C%93-brightgreen.svg)](CHECKLIST.md)

Example: manpm

Checklist

• watch the egghead.io series How to Write an Open Source JavaScript Library; it is extremely useful for any NPM project (OSS or closed-sourced).
• start unit testing right away, pick your unit testing framework
• start linting code to prevent obvious problems, like misspelled variable. eslint, jshint, jscs or all of them together gulp-lint-everything
• run linting and unit tests on each commit locally. pre-git, ghooks and use ban-sensitive-files to avoid committing sensative files (like private keys).
• use code quality as a service tool to fight creeping code complexity. Codacy, CodeClimate, BitHound
• validate commit message using pre-git or commitizen with validate-commit-msg. This enables other tools, like intelligent release notes.
• use logging library to show more information during debugging or verbose mode. debug, logdown
• show the project's GitHub open issues on demand or on commit using git-issues
• setup continuous integration server, like TravisCI or CircleCI (or wait until you set up semantic-release which will set up TravisCI for you).
• add badges to the README to make broken unit tests or out of date dependencies visible
• ci server badge
• published NPM package info NodeICO
• production and dev dependencies being out of date david-dm
• semantic release badge
• code quality badges
• insecure code or dependencies
• check module published size and white list only necessary files, tutorial
• setup semantic-release to automate publishing and avoid breaking semver. This is important, but is currently broken in too many projects. Even this checklist is using semver!
• avoid surprizes by using exact versions of the top level dependencies. Use save-exact NPM setting and exact-semver to enforce it.
• setup a script to reliably update out of date dependencies using next-update
• setup automatic pull requests when newer versions of dependencies appear greenkeeper.io
• if writing a CLI tool, add a way to check if it is out of date and should be upgraded; update-notifier
• scan dependencies and code for known security vulnerabilities. snyk, NodeSecurity
• catch missing or invalid package.json values using grunt-nice-package or fixpack
• write simple installation commands for your module
• write "quick intro" example showing the main feature of your module
• add CONTRIBUTING.md file with clear guidelines how others can add new features or fix bugs in your module. Atom editor and lodash have excellent examples to follow. When GitHub finds a CONTRIBUTING.md file it shows a message to anyone opening an issue.
• generate documentation automatically. xplain is my own tool for JS to HTML/Markdown generation
• place most of the public API documentation in README file for simple retrieval. This allows other developers to find relevant sections right from the command line manpm or by looking up npm home package-name
• use a library to output the correct plural forms of words in the user messages pluralize

Source: npm-module-checklist

Advanced

If you include the separate checklist file, you can automatically insert / update it inside the README. Setup the markdown update as a step in your build process using update-markdown.

Contributing

Everyone is welcome to submit pull requests with new content. I just ask to check before submitting a new content that:

• it is not covered by an item that already is in the list.
• if there is an open issue, please reference it in your commit message. You can even check the list of issues from command line before committing npm run issues.
• has links to an explanation why it is a good idea and tools that help accomplish it.
• Make sure to run npm run build once to update the checklist inside README.md

Contributors

• Kent C. Dodds @kentcdodds
• Gleb Bahmutov @bahmutov

Small print

Author: Gleb Bahmutov © 2015

• @bahmutov
• glebbahmutov.com
• blog

License: MIT - do anything with the code, but don't blame me if it does not work.

Spread the word: tweet, star on github, etc.

Support: if you find any problems with this module, email / tweet / open issue on Github

npm-module-checklist's Issues

Move the checklist into separate markdown file

• move checklist into a markdown file
• embed into the README using https://github.com/bahmutov/update-markdown
• describe how one can just grab the checklist markdown and add to own project

validate package.json

make sure it is well-formatted

Add CONTRIBUTING.md

Both to this repo and to the checklist :-)

Add note about CLI tools checking being out of date

should warn

Add static code analysis todo

Tools like codacy, code climate, bithoudn

Setup semantic release

Probably lint the package.json and readme only for now, depends on semantic release cli issues

Add contributors to the readme

Embed version tag into CHECKLIST.md

And update it from the package.json?

Using snyk

I've also included snyk as part of my npm module test process to check for any security vulnerabilities in any dependencies

It might be worth a consideration to add to this list

Add reference to egghead series?

I think my egghead.io series really helps people get going. Where do you think this fits in?

Add generator to set up most of this

Checklists are helpful, but lots of this could be automated :-)

Broken list in the included checklist inside readme

Seems like something went wrong when updating the markdown inside the readme file, probably related to #10