published

📦 Opinionated NPM publish program

published helps streamline a git based workflow with package publishing through continues delivery. Developers control their branch and version strategies, and published takes care of logical conditioning of when to publish stable versions and/or release candidates.

Run without installation

npx published@1

npm exec published@1 --yes

Options

option	Description	Example
testing	Dry run	`npm exec published --yes -- --testing`
slack.webhook	Notify on Slack	`npm exec published --yes -- --slack.webhook $SLACK_WEBHOOK`
slack.channel	Change Slack webhook channel	`npm exec published --yes -- --slack.webhook $SLACK_WEBHOOK --slack.channel "#publish"`
quiet	Silent outputs and notifications	`npm exec published --yes -- --quiet`
git-tag	Push a tag to git, Only from `master`(latest-branch) or `latest` branch	`npm exec published --yes -- --git-tag`
prefix-git-tag	Choose a prefix that will be prepend to git tag. Only from `master`(latest-branch) or `latest` branch	`npm exec published --yes -- --git-tag --prefix-git-tag=my-prefix@`
on-publish	Execute shell command after a publish event	`npm exec published --yes -- --on-publish bash\ ./do-more.sh`
on-<tag>	Execute shell command after a publish event with this tag (executes after on-publish)	`npm exec published --yes -- --on-latest 'echo "Published!"'`
latest-branch	Branch that is considered latest (default is 'master')	`npm exec published --yes -- --latest-branch stable`
tag-name	Tag name to be used regardless of config. If performed from a branch other than `master`, needs to be used in conjunction with `latest-branch` option	`npm exec published --yes -- --tag-name next --latest-branch next`
no-sha	Disables the commit's SHA suffix for RC versions	`npm exec published --yes -- --no-sha`

TL;DR

Branch type	action
Feature branch	Release RC versions on tag by branch name.
Master (latest) branch	Release clean semver on "latest" tag.

NPM Permissions

In order to publish an NPM package as a privileged user, create an NPM configuration file. One way to do it is to hide the token in an environment variable and add this preceding step:

echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc

Flow

Feature branch

Publish only versions with a pre-release section containing rc string
Unless the --no-sha flag was passed, branch versions get a suffix that matches the commit ID, so you can re install the same tag and get updates
Tags are named after the branch name

"master" branch

Only publish clean semver versions, no pre-release
Publish versions to tag "latest" (or publishConfig.tag from package.json)

* using latest-branch option will switch its behaviour with master

"latest" branch

Same as master, but will ignore publishConfig.tag setting.
Use this if your master branch points to "next" through publishConfig.tag

Examples

branch	version	publish	tag	w/o sha
`my_feature_branch`, `next`	`1.3.0`	nothing	N/A	-
`my_feature_branch`, `next`	`1.3.1-alpha`	nothing	N/A	-
`my_feature_branch`, `next`	`1.3.1-rc`	`1.3.1-rc`	`my_feature_branch`, `next`	✓
`my_feature_branch`, `next`	`1.3.1-rc.1`	`1.3.1-rc.1`	`my_feature_branch`, `next`	✓
`my_feature_branch`, `next`	`1.3.1-rc`	`1.3.1-rc-c447f6a`	`my_feature_branch`, `next`	✕
`my_feature_branch`, `next`	`1.3.1-rc.1`	`1.3.1-rc.1-c447f6a`	`my_feature_branch`, `next`	✕
`master`, `latest`	`1.3.0`	`1.3.0`	`latest`	-
`master`, `latest`	`1.3.0-beta`	Throws Error	N/A	-
`master`, `latest`	`1.3.0-rc`	Throws Error	N/A	-

* using latest-branch option will switch its behaviour with master

Package icon by Julien Deveaux from the Noun Project