publish-node-npm-module-tutorial.txt

publish-node-npm-module-tutorial.txt

gone -- http://quickleft.com/blog/creating-and-publishing-a-node-js-module

Publishing a node module
https://codeburst.io/how-to-create-and-publish-your-first-node-js-module-444e7585b738
 - also shows how to do travis integration

NPM version updating and hook scripts
https://docs.npmjs.com/cli/v6/commands/npm-version

NPM release management
https://bytesafe.dev/posts/npm-release-management/

===================

npm set init.author.name "Brent S.A. Cowgill"
npm set init.author.email "xxx@xxx.ccc"
npm set init.author.url "http://github.com/bcowgill"
npm login
npm adduser

Username: bcowgill (now bcowgi11)
Password:
Email: (this IS public) xxx@xxx.ccc
npm http PUT https://registry.npmjs.org/-/user/org.couchdb.user:bcowgill
npm http 201 https://registry.npmjs.org/-/user/org.couchdb.user:bcowgill

This user pw lost, I am now bcowgi11
npm login before we publish.

===================

npm init

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sane defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
name: (perljs)
version: (0.0.0)
description: Perl for Javascript. Just some functions that a perl developer miss
es in Javascript.
entry point: (index.js) perl.js
test command:
git repository: (https://github.com/bcowgill/perljs.git)
keywords: perl
license: (ISC) The Unlicense
About to write to D:\d\s\github\perljs\package.json:

{
  "name": "perljs",
  "version": "0.0.0",
  "description": "Perl for Javascript. Just some functions that a perl developer
 misses in Javascript.",
  "main": "perl.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/bcowgill/perljs.git"
  },
  "keywords": [
    "perl"
  ],
  "author": "Brent Cowgill <brent@blismedia.com> (http://github.com/bcowgill)",
  "license": "The Unlicense",
  "bugs": {
    "url": "https://github.com/bcowgill/perljs/issues"
  },
  "homepage": "https://github.com/bcowgill/perljs"
}


Is this ok? (yes) yes

===================

npm install mocha --save-dev
npm install chai --save-dev

package.json
  "scripts": {
    "test": "./node_modules/.bin/mocha --reporter spec"
  },


npm test

===================

update readme and package.json version/license then tag and release

git tag 0.1.0
git push origin master --tags

Verify that the package installs properly. From your package root directory, enter the following to install your package globally.

npm install . -g
Check to see if it exists.

npm ls -g

direct install from github before publishing on npm registry

npm install git://github.com/bcowgill/perljs.git
npm install git://github.com/bcowgill/perljs.git#0.1.0

test module actually works

node
var p=require('perljs');
console.log(p.qq('what'));
process.exit();

===================

npm publish

$ npm publish
npm http PUT https://registry.npmjs.org/perljs
npm+ perljs@0.1.0
 http 201 https://registry.npmjs.org/perljs

$ cd somewhere; npm install perljs
perljs@0.1.0 node_modules\perljs

node
var p=require('perljs');
console.log(p.qq('what'));
process.exit();

Visible on npmjs.org now.
https://www.npmjs.org/package/perljs

===================

jsDoc

npm install -g jsdoc@"<=3.3.0"

./node_modules/.bin/jsdoc yourJavaScriptFile.js

 npm install -g mocha jsdoc

More links on documenting

best documentation for node
http://samwize.com/2014/01/31/the-best-documentation-generator-for-node/
docco adds to jsdoc
http://jashkenas.github.io/docco/
themes
https://github.com/terryweiss/docstrap

=======================
Bower is end of life, suggests to use yarn, parcel, etc.

bower

npm install -g bower

bower init

creates bower.json based on package.json

bower register ./bower.json ??? will this work ? no
if no, bower register perljs https://github.com/bcowgill/perljs.git
takes an hour or so to show up bower search page
http://bower.io/search/?q=perljs

UMD github shows how to make a node/amd compatible module
https://github.com/umdjs/umd/blob/master/templates/returnExports.js
git clone https://github.com/umdjs/umd

For in browser CommonJS module loading
bower install require1k --save-dev

Need a local web server for require to work
npm install grunt-contrib-connect --save-dev

For in browser AMD module loading
bower install --save-dev definejs

=======================
Browser based testing.

using an html page and grunt-connect

npm install --save-dev requirejs
then just had to set up a test/index.html test/setup-test-framework.js
and test-suite-browser.js

=======================
using karma and a browser or phantomjs

phantomjs:
npm install --save-dev phantomjs

karma
npm install -g karma-cli
npm install --save-dev karma
npm install --save-dev karma-mocha
npm install --save-dev karma-chai
npm install --save-dev karma-requirejs
npm install --save-dev karma-sinon
npm install --save-dev karma-sinon-chai
npm install --save-dev karma-phantomjs-launcher
npm install --save-dev grunt-karma

karma init   to create a karma.conf.js and test-main.js

then fiddled around trying to get the chai library to reqire properly
but couldn't do it. tried chai in the frameworks list and also tried
to require() it from setup-test-framework but couldn't get it working.

gave up as spent a lot of time on it for little gain.
difficulty may be in trying to have the tests written so they run in both
node and browser.

these documents may be helpful for next time, try it in a virgin project.
https://sean.is/writing/client-side-testing-with-mocha-and-karma/
https://github.com/bbraithwaite/karma-seed

=======================
using prettier and grunt-prettier for uniform code styling.

npm install --save-dev prettier grunt-prettier

prettier runs much faster than grunt-prettier.

uses .prettierrc.json for the npm script command and internally configured options for the grunt prettier command

Can convert all tabs to spaces in files then check that prettier has been configured to work on all files:
INDENT_TAB=0 INDENT=2 fix-spaces.sh *.json .*.json lib/perl.js Gruntfile.js test/*.js test/*.html
npm run prettier
or grunt prettier


=======================
adding husky to run the tests before commit / push
https://typicode.github.io/husky/#/

npm install --save-dev husky pinst && npm exec husky init

husky - Git hooks installed
husky - created .husky/pre-commit
⚠ if you're publishing your package to npm, you need to disable postinstall script using pinst.
see https://typicode.github.io/husky/#/?id=install

sources a ~/.huskyrc definition file - may be needed with nvm
keeps husky hooks in .husky dir in project.
needs git 2.9 or better.

npx husky add .husky/pre-push 'npm build'
echo '#!/bin/sh' > .git/hooks/pre-push
echo '[ -x .husky/pre-push ] && .husky/pre-push $1 $2' >> .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Removed the pre-push hook as build will always update files


=======================
adding eslint to replace jshint (will keep configuration alongside each other for now)
https://www.npmjs.com/package/eslint
https://www.npmjs.com/package/grunt-eslint
https://eslint.org/docs/developer-guide/nodejs-api#cliengine

npm install --save-dev eslint grunt-eslint
./node_modules/.bin/eslint --init
.eslintrc.json.prompted
$ eslint --init
✔ How would you like to use ESLint? · style
✔ What type of modules does your project use? · commonjs
✔ Which framework does your project use? · none
✔ Does your project use TypeScript? · No / Yes
✔ Where does your code run? · browser, node
✔ How would you like to define a style for your project? · prompt
✔ What format do you want your config file to be in? · JSON
✔ What style of indentation do you use? · tab
✔ What quotes do you use for strings? · single
✔ What line endings do you use? · unix
✔ Do you require semicolons? · No / Yes
Successfully created .eslintrc.json file in /home/me/workspace/play/perljs

Tried again scanning my code.
.eslintrc.json.scanned
$ eslint --init
✔ How would you like to use ESLint? · style
✔ What type of modules does your project use? · commonjs
✔ Which framework does your project use? · none
✔ Does your project use TypeScript? · No / Yes
✔ Where does your code run? · browser, node
✔ How would you like to define a style for your project? · auto
✔ Which file(s), path(s), or glob(s) should be examined? · lib test
✔ What format do you want your config file to be in? · JSON
Determining Config: 100% [==============================] 1.1s elapsed, eta 0.0s 

Enabled 208 out of 258 rules based on 5 files.
Successfully created .eslintrc.json file in /home/me/workspace/play/perljs

And again with no style fixing.
.eslintrc.json.nostyle
$ eslint --init
✔ How would you like to use ESLint? · problems
✔ What type of modules does your project use? · commonjs
✔ Which framework does your project use? · none
✔ Does your project use TypeScript? · No / Yes
✔ Where does your code run? · browser, node
✔ What format do you want your config file to be in? · JSON
Successfully created .eslintrc.json file in /home/me/workspace/play/perljs

=======================
Adding nyc to replace istanbul for coverage as it is deprecated.
https://www.npmjs.com/package/nyc
Supported reporters: https://git.io/vHysA

npm install --save-dev nyc

You can add
// istanbul ignore if
// istanbul ignore else
// istanbul ignore next

Added scripts/*.css from nyc coverage output and modified for dark theme.
Also saved scripts/*.html coverage html for testing all color schemes
npm coverage commands will copy these CSS files to doc/coverage after a build

=======================
Adding htmllint and grunt-htmllint
https://github.com/htmllint/htmllint-cli
https://github.com/htmllint/grunt-htmllint
https://github.com/htmllint/htmllint/wiki/Options
https://github.com/htmllint/htmllint/wiki/Option-by-Error-Code

npm install --save-dev htmllint htmllint-cli grunt-htmllint
htmllint init

creates .htmllintrc configuration file
renamed .json and created a symlink.
ln -s .htmllintrc.json .htmllintrc


=======================
Adding stylelint and grunt-stylelint
https://github.com/stylelint/stylelint
https://www.npmjs.com/package/grunt-stylelint
https://github.com/stylelint/stylelint/blob/master/docs/user-guide/rules/list.md#possible-errors

npm install --save-dev stylelint stylelint-config-standard grunt-stylelint

manually create .stylelintrc.json


    --formatter, -f               [default: "string"]

      The output formatter: "compact", "json", "string", "tap", "unix" or "verbose".

	  verbose is nice

--report-needless-disables
--report-invalid-scope-disables
--report-descriptionless-disables

=======================
Created a Travis CI account
https://travis-ci.org/
Actually you log in with github ID and activate your chosen repositories.

add a .travis.yml

view travis builds on every push at https://travis-ci.org/github/bcowgill/perljs

Needed to install additional packages for running on travis:

pnpm install --save-dev grunt-cli grunt-legacy-util grunt-legacy-log dateformat eventemitter2 iconv-lite mkdirp jshint blanket gaze connect maxmin tiny-lr morgan uri-path sinon serve-static uglify-js serve-index node-http2 connect-livereload opn handlebars escodegen
\npm shrinkwrap

Created a make travis and npm travis target which runs the tests and lint without grunt
this time had to install:
abbrev mkdirp async handlebars escodegen nopt

=======================
Created a Coveralls account
https://coveralls.io/
Actually you log in with github ID and activate your chosen repositories.

And install coveralls

npm install --save-dev coveralls

nyc command needs reporter lcovonly added
and .travis.yml needs to run coverage instead of just tests.

=======================
Contributing.md template taken from babel
https://github.com/babel/babel/blob/master/CONTRIBUTING.md


=======================
Trying to use npm version to up the version number

npm version patch -m "release Version patch %s after toolchain updated"; echo == $? ==

tries to run:
/usr/bin/git status --porcelain=v1 -uno

which is invalid for my version of git,
/usr/bin/git status --porcelain -uno
works though...

our git is too old so we tell npm to skip the git command on the release command line and we do it ourself in our pre-version script.
npm version patch --no-git-tag-version -m "release Version patch %s after toolchain updated"; echo == $? ==

use this hack:
rm git; ln -s git.xxx git
export PATH=`pwd`:$PATH
npm version patch -m "release Version patch %s after toolchain updated"; echo == $? ==

to run with the git command and trace what git commands are being used.

\git reset HEAD npm-shrinkwrap.json package.json ; \git checkout -- package.json npm-shrinkwrap.json
rm local-git.log
\npm version patch -m "release Version patch %s after toolchain updated"; echo == $? ==

=== Summary of what happens when npm version command runs:

npm calls /usr/bin/git status --porcelain=v1 -uno  to check if the repo is clean.
the package.json preversion script runs
npm updates the version number in package.json and npm-shrinkwrap.json
the package.json version script runs
npm adds package.json and npm-shrinkwrap.json then commits and tags using the commit message provided.
	/usr/bin/git add /home/me/workspace/play/perljs/package.json
	/usr/bin/git add /home/me/workspace/play/perljs/npm-shrinkwrap.json
	/usr/bin/git commit -m release Version patch 0.3.4 after toolchain updated
	/usr/bin/git tag -m release Version patch 0.3.4 after toolchain updated v0.3.4
the package.json postversion script runs

=== Summary of what happens when npm publish command runs:

npm calls /usr/bin/git status --porcelain to check if the repo is clean (note this is too much, checks untracked files.)
npm calls /usr/bin/git symbolic-ref --short HEAD  to check that you are on the master branch. or asks if it is still ok to release.
npm calls /usr/bin/git rev-list --count --left-only @{u}...HEAD  to check that you have an upstream set and are at the HEAD revision.
the package.json prepublish script runs
the package.json prepublishOnly script runs
the package.json prepublishOnly script runs again!
the package.json publish script runs
the package.json postpublish script runs
the package.json publish script runs again!
the package.json postpublish script runs again!

When the scripts run twice, it runs once showing the module directory and again showing no directory.

We use a package/ directory as a semaphore to prevend doing the same thing twice in the post-publish script.

=======================

NPM package published:
https://www.npmjs.com/package/@bcowgi11/perljs

=======================

Adding GitHub badges to README and CONTRIBUTING pages.

https://www.makeuseof.com/badges-that-will-supercharge-your-github-repository/

More badge options here:
https://shields.io/
Allows you to construct your own personal badge URL/Markdown by filling in your user name/repo