Node.js npm Package Skeleton

Bootstrap a new Node.js npm package in five minutes or less.

Features

• Node.js's npm package structure.
• Fast, reliable, and secure dependency management with Yarn.
• Next generation JavaScript with Babel.
• Write debuggable examples with configurable options and arguments.
• Linting with the JavaScript Standard Style and JSON Lint.
• Automatically lint on changes with gulp.
• Futuristic debuggable unit testing with AVA.
• Code coverage reporting with Istanbul, nyc, and Codecov.
• Continuous testing and automated package publishing with CircleCI.
• Keep a CHANGELOG.
• Consistent coding with EditorConfig.
• Badges from Shields.io.

License

This repository is released into the public domain through CC0. The other copyright notices for this project are for the purpose of demonstrating the licensing of derived projects.

To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.

Bootstrapping a new project

1. Clone the master branch of this repository with

   $ git clone --single-branch git@github.com:meltwater/makenew-node-lib.git <new-node-lib>
   $ cd <new-node-lib>
   

   Optionally, reset to the latest version with

   $ git reset --hard <version-tag>
   

2. Create an empty (non-initialized) repository on GitHub.

3. Run

   $ ./makenew.sh
   

   This will replace the boilerplate, delete itself, remove the git remote, remove upstream tags, and stage changes for commit.

4. Create the required CircleCI environment variables with

   $ .circleci/envvars.sh
   

5. Review, commit, and push the changes to GitHub with

   $ git diff --cached
   $ git commit -m "Replace makenew boilerplate"
   $ git remote add origin git@github.com:meltwater/<new-node-lib>.git
   $ git push -u origin master
   

6. Ensure the CircleCI build passes, then publish the initial version of the package with

   $ nvm install
   $ yarn
   $ npm version patch
   

7. Update the GitHub branch protection options for master to require all status checks to pass. Disable the GitHub repository projects and wiki options (unless desired). Add any required GitHub teams or collaborators to the repository. Enable GitHub data services for dependency analysis. Enable Codecov.

8. Search for all TODO comments to add your first module.

Updating from this skeleton

If you want to pull in future updates from this skeleton, you can fetch and merge in changes from this repository.

Add this as a new remote with

$ git remote add upstream git@github.com:meltwater/makenew-node-lib.git

You can then fetch and merge changes with

$ git fetch --no-tags upstream
$ git merge upstream/master

Changelog for this skeleton

Note that CHANGELOG.md is just a template for this skeleton. The actual changes for this project are documented in the commit history and summarized under Releases.

Description

TODO

Installation

Add this as a dependency to your project using npm with

$ npm install @meltwater/makenew-node-lib

or using Yarn with

$ yarn add @meltwater/makenew-node-lib

Usage

See the complete API documentation and working examples.

This package provides an async function which checks if its argument is true.

import isTrue from '@meltwater/makenew-node-lib'

const logTrue = async () => {
  const trueValue = await isTrue(true)
  console.log(trueValue)
}

logTrue().catch(err => { console.log(err) })
// true

Development Quickstart

$ git clone https://github.com/meltwater/makenew-node-lib.git
$ cd makenew-node-lib
$ nvm install
$ yarn

Run each command below in a separate terminal window:

$ yarn run watch
$ yarn run test:watch

Development and Testing

Source code

The makenew-node-lib source is hosted on GitHub. Clone the project with

$ git clone git@github.com:meltwater/makenew-node-lib.git

Requirements

You will need Node.js with npm, Yarn, and a Node.js debugging client.

Be sure that all commands run under the correct Node version, e.g., if using nvm, install the correct version with

$ nvm install

Set the active version for each shell session with

$ nvm use

Install the development dependencies with

$ yarn

CircleCI

CircleCI should already be configured: this section is for reference only.

The following environment variables must be set on CircleCI:

• NPM_TOKEN: npm token for installing and publishing packages.
• NPM_TEAM: npm team to grant read-only package access (format org:team, optional).
• CODECOV_TOKEN: Codecov token for uploading coverage reports (optional).

These may be set manually or by running the script ./.circleci/envvars.sh.

Development tasks

Primary development tasks are defined under scripts in package.json and available via yarn run. View them with

$ yarn run

Production build

Lint, test, and transpile the production build to dist with

$ yarn run dist

Publishing a new release

Release a new version using npm version. This will run all tests, update the version number, create and push a tagged commit, and trigger CircleCI to publish the new version to npm.

• Update the CHANGELOG before each new release after version 1.
• New versions are released when the commit message is a valid version number.
• Versions are only published on release branches: master branch or any branch matching ver/*.
• If branch protection options are enabled, you must first run npm version on a separate branch, wait for the commit to pass any required checks, then merge and push the changes to a release branch.
• Do not use the GitHub pull request button to merge version commits as the commit tagged with the new version number will not match after merging.

Examples

See the full documentation on using examples.

View all examples with

$ yarn run example

Linting

Linting against the JavaScript Standard Style and JSON Lint is handled by gulp.

View available commands with

$ yarn run gulp --tasks

Run all linters with

$ yarn run lint

In a separate window, use gulp to watch for changes and lint JavaScript and JSON files with

$ yarn run watch

Automatically fix most JavaScript formatting errors with

$ yarn run format

Tests

Unit and integration testing is handled by AVA and coverage is reported by Istanbul and uploaded to Codecov.

• Test files end in .spec.js.
• Unit tests are placed under lib alongside the tested module.
• Integration tests are placed in test.
• Static files used in tests are placed in fixtures.

Watch and run tests on changes with

$ yarn run test:watch

If using AVA snapshot testing, update snapshots with

$ yarn run test:update

Generate a coverage report with

$ yarn run report

An HTML version will be saved in coverage.

Debugging tests

Create a breakpoint by adding the statement debugger to the test and start a debug session with, e.g.,

$ yarn run test:inspect lib/true.spec.js

Watch and restart the debugging session on changes with

$ yarn run test:inspect:watch lib/true.spec.js

Contributing

The author and active contributors may be found in package.json,

$ jq .author < package.json
$ jq .contributors < package.json

To submit a patch:

1. Request repository access by submitting a new issue.
2. Create your feature branch (git checkout -b my-new-feature).
3. Make changes and write tests.
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create a new Pull Request.

License

This npm package is Copyright (c) 2016-2020 Meltwater Group.

Warranty

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.