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" usingnpm 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-runThe 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`- 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`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
```sh
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:
```sh
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:
```json
{
"prePublishScript": false,
}
```- 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:
```yaml
https://npmjs.com/advisories/12
https://npmjs.com/advisories/577
```
- you may perform vulnerabilities check only for a specific vulnerability level: `critical`, `high`, `moderate` or `low`.
To do this create an `audit.opts` file in the root of your project with content like the following:
```sh
--audit-level=high
```
The above example will enable to report only vulnerabilities of level `critical` and `high`
- if you want to disable this validation, run the command:
```sh
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:
```json
{
"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:
```sh
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:
```json
{
"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:
```sh
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:
```json
{
"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](.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 the `package.json` file has no `files` section, consider adding `.sensitivedata` to the `.npmignore` file.
- if you want to disable this validation, run the command:
```sh
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:
```json
{
"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` and `release`:
```sh
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:
```json
{
"validations": {
"branch": "/(master|release)/",
}
}
```
- if you want to disable this validation, run the command:
```sh
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:
```json
{
"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:
```sh
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:
```json
{
"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:
```json
{
"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 the `npm 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.
```sh
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:
```json
{
"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](https://docs.npmjs.com/cli/publish) 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 the `publishTag` property:
```json
{
"publishTag": "alpha"
}
```
- run publish-please (publish-please will automatically add on the publish command the option `--tag alpha`):
```sh
npx publish-please
```
or
```sh
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:
```sh
npx publish-please config
Do you want manually confirm publishing? No
```
or directly edit the property `confirm` in the `.publishrc` file:
```json
{
"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:
```sh
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:
```json
{
"postPublishScript": "npm run my-post-publish-script"
}
```- to disable a post-publish script:
```sh
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:
```json
{
"postPublishScript": ""
}
```Upgrading to latest publish-please version
- If you are running node 8 or above, and if you have in the
package.jsonfile an already existingprepublishscript, you should rename that script toprepublishOnlyafter you have upgraded publish-please.
- Run
npm help scriptsto get more details.
Running in CI mode
You can execute publish-please in CI mode by adding the--ci option:npm run publish-please --cior
npx publish-please --ciThis 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-pleaseOnce 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-pleaseCheck out my other packages used by this tool
- cp-sugar - Some sugar for childprocess module.
- elegant-status - Create elegant task status for CLI.
