KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #deepseek-harness #typescript #ai-agent #codex #developer-tools #claude-code #windows #mcp #python #desktop-app

publish-please

★ 736 Open GitHub ↗

Safe and highly functional replacement for `npm publish`.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Publish, please!
Safe and highly functional replacement for `npm publish`.

[![Build Status](https://travis-ci.org/inikulin/publish-please.svg?branch=master)](https://travis-ci.org/inikulin/publish-please)
[![npm version](https://img.shields.io/npm/v/publish-please.svg)](https://www.npmjs.com/package/publish-please)
[![Dependency Status](https://david-dm.org/inikulin/publish-please.svg)](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:

![dry-run-demo-with-errors](https://raw.githubusercontent.com/inikulin/publish-please/master/media/dry-run-with-errors.gif)

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:

![dry-run-demo-success](https://raw.githubusercontent.com/inikulin/publish-please/master/media/dry-run-demo-success.gif)

### **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
```
![publish-demo-success](https://raw.githubusercontent.com/inikulin/publish-please/master/media/publish-demo-success.gif)

## 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
        ```

```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
```

```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) (ifaaan@gmail.com)

-------------------------------------------------------------
## Maintainer
[Henri d'Orgeval](https://github.com/hdorgeval)

publish-please

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README