publish-please
v5.5.2
Published
Safe and highly functional replacement for `npm publish`.
Downloads
8,866
Readme
Publish, please!
Safe and highly functional replacement for npm publish
.
Publish-please enables you to :
- Validate your package before publishing to the registry
- Publish to the registry on sucessfull validation
- Run any script on successfull publishing
Publish-please is versatile enough to be used only as a validation tool before publishing or as an all-in-one tool when you want to manually handle your releases.
See how the TestCafe team uses publish-please when bumping to the next release.
Other topics:
- Installing publish-please locally
- Upgrading to latest publish-please version
- Running in CI mode
- Customize the Validation Workflow
- Customize the Publishing Workflow
Validate your package before publishing to the registry
There are numerous ways to "shoot yourself in the foot" using npm publish
.
publish-please
enables you to check that what will be sent to the registry is valid, free of vulnerabilities and free of useless files.
Before running npm publish
, run this command at the root of your project folder:
npx publish-please --dry-run
The following example shows that you are about to push your test files to the registry:
When all validations pass, publish-please will show you the exact content of the package that will be sent to the registry, so you can check everything is included in the package:
The Validation Workflow performs by default the following actions:
npm test
- Check that all tests pass
Checking for the vulnerable dependencies
- Perform vulnerable dependencies check using
npm audit
- Perform vulnerable dependencies check using
Checking for the uncommitted changes
- Check that there are no uncommitted changes in the working tree
Checking for the untracked files
- Check that there are no untracked files in the working tree
Checking for the sensitive and non-essential data in the npm package
- Check that the npm package will not embed sensitive files or useless files (like test files)
Validating branch
- Check that current branch is master
Validating git tag
- Check that git tag matches version specified in the
package.json
- Check that git tag matches version specified in the
Customize the Validation Workflow
npm test
- you can run any kind of command in place of the
npm test
command. For this you need a.publishrc
configuration file at the root of your project. To create or modify the.publishrc
file, run the command
npx publish-please config Do you want to run any scripts before publishing (e.g. build steps, tests)? Yes Input pre-publish script: npm run my-own-script
if you want to disable this validation, run the command:
npx publish-please config Do you want to run any scripts before publishing (e.g. build steps, tests)? No
or directly edit the property
prePublishScript
in the.publishrc
file:{ "prePublishScript": false, }
- you can run any kind of command in place of the
Checking for the vulnerable dependencies
This validation check uses
npm audit
under the hood. This validation check performs only if npm version is 6.1.0 or above.you may prevent specific vulnerabilities to be reported by publish-please by creating a
.auditignore
file in the root of your project with content like the following:https://npmjs.com/advisories/12 https://npmjs.com/advisories/577
you may perform vulnerabilities check only for a specific vulnerability level:
critical
,high
,moderate
orlow
. To do this create anaudit.opts
file in the root of your project with content like the following:--audit-level=high
The above example will enable to report only vulnerabilities of level
critical
andhigh
if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that your package doesn`t have vulnerable dependencies before publishing? No
or directly edit the property
vulnerableDependencies
in the.publishrc
file:{ "validations": { "vulnerableDependencies": false, } }
Checking for the uncommitted changes
This validation checks that there are no uncommitted changes in the working tree.
if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that there are no uncommitted changes in your working tree before publishing? No
or directly edit the property
uncommittedChanges
in the.publishrc
file:{ "validations": { "uncommittedChanges": false, } }
Checking for the untracked files
This validation checks that there are no untracked files in the working tree.
if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that there are no files that are not tracked by git in your working tree before publishing? No
or directly edit the property
untrackedFiles
in the.publishrc
file:{ "validations": { "untrackedFiles": false, } }
Checking for the sensitive and non-essential data in the npm package
This validation checks there is no sensitive files and no useless files inside the to-be-published package. This validation check performs only if npm version is 5.9.0 or above.
This validation is able to detect the following files:
- Benchmark files
- Configuration files
- CI
- eslint
- GitHub
- JetBrains
- Visual Studio Code
- Coverage files
- Demo files
- Dependency directories
- Doc files
- Example files
- Log files
- Private SSH key
- Script files
- Secret files
- Source files
- Temp files
- Test files
- Zip files
- Output of 'npm pack'
sensitive and non-essential files are defined inside this built-in .sensitivedata file.
you may completely override this file by creating a
.sensitivedata
file in the root of your project so that this validation fits your needs.- if you create your own
.sensitivedata
file, and thepackage.json
file has nofiles
section, consider adding.sensitivedata
to the.npmignore
file.
- if you create your own
if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that there is no sensitive and non-essential data in the npm package? No
or directly edit the property
sensitiveData
in the.publishrc
file:{ "validations": { "sensitiveData": false, } }
Validating branch
This validation checks that current branch is
master
.You can set the branch as a regular expression to be able to use publish-please in a multiple branches scenario like
master
andrelease
:npx publish-please config Would you like to verify that you are publishing from the correct git branch? Yes Which branch should it be? /(master|release)/
or directly edit the property
branch
in the.publishrc
file:{ "validations": { "branch": "/(master|release)/", } }
if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that you are publishing from the correct git branch? No
or directly edit the property
branch
in the.publishrc
file:{ "validations": { "branch": false, } }
Validating git tag
This validation checks that git tag matches version specified in the
package.json
.if you want to disable this validation, run the command:
npx publish-please config Would you like to verify that published commit has git tag that is equal to the version specified in package.json? No
or directly edit the property
gitTag
in the.publishrc
file:{ "validations": { "gitTag": false, } }
if the git tag contains a prefix to the version like for example
foo-v0.0.42
, supply the prefix in the.publishrc
file:{ "validations": { "gitTag": "foo-v", } }
Publish to the registry on sucessfull validation
To publish on successfull validation, run the following command:
npx publish-please
Customize the Publishing Workflow
publish command
You can customize the command used by publish-please to publish to the registry. By default this command is
npm publish
. In some situation you may need to add specific options on thenpm publish
command (the--tag
option must not be set here because this option is managed by the publish Tag configuration (see below)).You may also want to run your own publish script instead of the
npm publish
command.npx publish-please config Specify publishing command which will be used to publish your package: npm publish --userconfig ~/.npmrc-myuser-config
or directly edit the property
publishCommand
in the.publishrc
file:{ "publishCommand": "npm publish --userconfig ~/.npmrc-myuser-config" }
publish Tag
You can set the tag with which the package will be published. See npm publish docs for more info. By default publish please will run the
npm publish
command with the option--tag latest
.When you want to manually release an alpha version for version
x.y.z
on npm, you should take the following steps:in package.json: bump version to
x.y.z-alpha.1
,commit and push;
on github: tag this commit with
vx.y.z-alpha.1
in the
.publishrc
file edit thepublishTag
property:{ "publishTag": "alpha" }
run publish-please (publish-please will automatically add on the publish command the option
--tag alpha
):npx publish-please
or
npm run publish-please
if you have installed locally publish-please
confirm
by default a confirmation will be asked before publishing.
if you want to disable this confirmation, run the command:
npx publish-please config Do you want manually confirm publishing? No
or directly edit the property
confirm
in the.publishrc
file:{ "confirm": false }
Run any script on successfull publishing
Publish-please enables you to run a command after successful publishing. Use it for release announcements, uploading binaries, etc.
to configure a post-publish script:
npx publish-please config Do you want to run any scripts after succesful publishing (e.g. releaseannouncements, binary uploading)? Yes Input post-publish script : npm run my-post-publish-script
or directly edit the property
postPublishScript
in the.publishrc
file:{ "postPublishScript": "npm run my-post-publish-script" }
to disable a post-publish script:
npx publish-please config Do you want to run any scripts after succesful publishing (e.g. releaseannouncements, binary uploading)? No
or directly edit the property
postPublishScript
in the.publishrc
file:{ "postPublishScript": "" }
Upgrading to latest publish-please version
If you are running node 8 or above, and if you have in the
package.json
file an already existingprepublish
script, you should rename that script toprepublishOnly
after you have upgraded publish-please.Run
npm help scripts
to get more details.
Running in CI mode
You can execute publish-please in CI mode by adding the --ci
option:
npm run publish-please --ci
or
npx publish-please --ci
This option will turn off the default elegant-status reporter in favor of the built-in CI reporter. Use this option to disable emoji and spinner usage. When publish-please executes in a CI (Teamcity, Travis, AppVeyor, ...), the CI reporter is automatically activated.
Installing publish-please locally
publish-please can be installed locally:
npm install --save-dev publish-please
Once installed, the configuration wizard will enable you to configure the validation and publishing workflow.
From now on you cannot use anymore the npm publish
command in your project.
But don't worry it's done for the good reason to prevent you or your co-workers run unsafe publishing process. Use publish-please instead of npm publish
:
npm run publish-please
Check out my other packages used by this tool
- cp-sugar - Some sugar for child_process module.
- elegant-status - Create elegant task status for CLI.
Author
Ivan Nikulin ([email protected])