An opinionated NPM module structure format
Inspired by feross/standard and ahmadnassri/npm-package-generator
No decisions to make. You don't have to stress about folder structure or naming standards. It just works
This module saves you (and others!) time in two ways:
- No configuration. The easiest way to start an npm module project, or see if yours is up to snuff
- Catch style errors before they're submitted in PRs. Saves precious code review time by eliminating back-and-forth between maintainer and contributor.
npm install npm-standard
- keep your package dependencies lean, only include useful files for developers when running
npm install
(see package.json + .npmignore files) - Expose your modules library files in
lib/
, if not included in your normal dependencies
- use
.env
files anddotenv
for configuration, following the tenets of a twelve-factor app- only use
dotenv
in your application entry point, or library if applicable. - supply a
.env.template
file for your users, with applicable variables included.
- only use
- use
.travis.yaml
files to ensure Travis CI build success- use container mode in
travis
and leverage folder caching.
- use container mode in
- use
.editorconfig
files for editor standardization
- Put all tests in a
test/
subfolder - Put any applicable fixtures in
test/fixtures
- use
mocha
for testing - use
istanbul
to generate coverage reports - publish coverage reports to codeclimate (requires configuring travis with the appropriate
CODECLIMATE_REPO_TOKEN
) - use
standard
andechint
for linting files
- enforce
standard
&echint
by running onpretest
- always generate code coverage reports by running
istanbul
onposttest
- if your module requires them, place templates in a
templates/
folder in the root of your module for easy access.
While these are less important, there are a number of standard libs that work very well for common tasks:
- For debugging, try using
debug-log
ortrace-debug-log
to provide helpful debugging messages without the use ofconsole.log
- CLI Module? try
commander
to provide a CLI (Command Line Interface)
Always include a LICENSE
file in your module. This will let developers know the usage parameters of your package. I suggest linking whatever license you use to the appropriate page on tldrlegal.com for a layman terms application of your licensing rules.
- Include a Table of Contents in large doc files, linking to the appropriate subheadings **(this heading, for example, would be
[Docs](#docs)
in a ToC) - Include a
CONTRIBUTING
file to your module so people wanting to help out know where to find info about it. Place this in the root of your module so Github knows where to find it. - Include any installation information in
docs/INSTALL.md
- Include an API document at
docs/API.md
- Maintain an active
CHANGELOG.md
in the root of your module - Link all four documents in your
README.md
file
Note: If your docs files are especially small, you can forgo putting them in separate files, and just keep them in your README.md
file.
/package-name/
├── bin
│ └── package-name
├── docs
│ ├── API.md
│ └── INSTALL.md
├── .editorconfig
├── .env.example
├── .gitattributes
├── .gitignore
├── .jshintrc
├── lib
│ └── index.js
├── templates
├── LICENSE
├── CONTRIBUTING
├── CHANGELOG.md
├── .npmignore
├── package.json
├── README.md
├── src
│ └── index.js
├── test
│ ├── fixtures
│ └── index.js
└── .travis.yml
You can lint the module you are in to see if it conforms to this style guide by running in the command line
npm-standard
This will run tests against the folder structure and files and give warnings for any additional files than what is listed here, and give errors for missing files.
If you want to convert the folder you are in to npm-standard, you can do so via
npm-standard init
or
npm-standard fix
Both of these commands will lint the current directory, and fill in any missing files. It will also check the files present for proper structure and content, specifically configuration files for missing items.