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

• 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

  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,
    }

• 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 or low. To do this create an audit.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 and high

  • 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 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:

    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 and release:

    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 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 publishcommand.

  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 the publishTag 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 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:

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])

Maintainer

Henri d'Orgeval