Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/inikulin/publish-please
Safe and highly functional replacement for `npm publish`.
https://github.com/inikulin/publish-please
Last synced: 12 days ago
JSON representation
Safe and highly functional replacement for `npm publish`.
- Host: GitHub
- URL: https://github.com/inikulin/publish-please
- Owner: inikulin
- License: mit
- Created: 2015-12-03T17:36:48.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-08-24T04:21:01.000Z (3 months ago)
- Last Synced: 2024-10-18T18:57:35.276Z (21 days ago)
- Language: JavaScript
- Homepage:
- Size: 3.25 MB
- Stars: 737
- Watchers: 8
- Forks: 23
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Audit: audit.opts
Awesome Lists containing this project
- awesome-npm - publish-please - Publish packages safely and gracefully. (Packages / Publishing)
- awesome-npm - publish-please - Publish packages safely and gracefully. (Packages / Publishing)
README
# Publish, please!
Safe and highly functional replacement for `npm publish`.
[](https://travis-ci.org/inikulin/publish-please)
[](https://www.npmjs.com/package/publish-please)
[](https://david-dm.org/inikulin/publish-please)
Publish-please enables you to :
- [Validate your package before publishing to the registry](#Validate-your-package-before-publishing-to-the-registry)
- [Publish to the registry on sucessfull validation](#Publish-to-the-registry-on-sucessfull-validation)
- [Run any script on successfull publishing](#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](https://github.com/DevExpress/testcafe) team uses publish-please when [bumping to the next release](https://github.com/DevExpress/testcafe/commit/ab1f5ad430f307c224723a15c6425a41f25087df).
Other topics:
- [Installing publish-please locally](#Installing-publish-please-locally)
- [Upgrading to latest publish-please version](#Upgrading-to-latest-publish-please-version)
- [Running in CI mode](#Running-in-CI-mode)
- [Customize the Validation Workflow](#Customize-the-Validation-Workflow)
- [Customize the Publishing 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:
```sh
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`
- **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:
```sh
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.json` file an already existing `prepublish` script, you should rename that script to `prepublishOnly` 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:
```sh
npm run publish-please --ci
```
or
```sh
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:
```sh
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`:
```sh
npm run publish-please
```
-------------------------------------------------------------
## Check out my other packages used by this tool
- [cp-sugar](https://github.com/inikulin/cp-sugar) - Some sugar for child_process module.
- [elegant-status](https://github.com/inikulin/elegant-status) - Create elegant task status for CLI.
-------------------------------------------------------------
## Author
[Ivan Nikulin](https://github.com/inikulin) ([email protected])
-------------------------------------------------------------
## Maintainer
[Henri d'Orgeval](https://github.com/hdorgeval)