Publish, please!

Safe and highly functional replacement for `npm publish`.

You could also use publish-please only as an ultimate check before publishing: `npx publish-please --dry-run`

There are numerous ways to "shoot yourself in the foot" using npm publish. The purpose of this module is to replace npm publish for your packages with safe and more functional alternative, which will allow you to:

• Run tests or build steps before publishing (because prepublish is broken).
• Perform check for the sensitive and non-essential data in your package to be sure that you didn't leak it by accident (Further reading: Do not underestimate credentials leaks).
• Perform check for vulnerable dependencies using npm audit data.
• Check that you are in the correct git branch.
• Check that git tag matches version specified in the package.json.
• Check that there are no uncommitted changes in the working tree.
• Check that there are no untracked files in the working tree.
• Force usage of the npm publish tag there necessary, so you'll be sure you're not publishing preview version of your package as a release version.
• Get release summary and publishing confirmation.
• Configure publishing using built-in configuration wizard.

Getting started ( or use npx directly )

Setup process of publish-please is quite trivial - just run

npm install --save-dev publish-please

in your project's directory.

Once it finish installing, publish-please will automatically run it's configuration wizard, which will guide you through some simple steps to setup features you want to use:

If you forgot to configure something or just changed your mind and want to change configuration, just run

npm run publish-please config

to return to wizard.

So, once you've done with wizard from now on npm publish for your package is disabled (Muahahaha 😈):

But don't worry it's done for the good reason to prevent you or your co-workers run unsafe publishing process. Use awesome version instead:

npm run publish-please

Options

• prePublishScript - Specifies command that will be run before publish (e.g. npm test). Use it for builds and tests. Default: npm test.
• postPublishScript - Specifies command that will be run after successful publishing. Use it for release announcements, creating a GitHub release, uploading binaries, etc. Default: `` (no command).
• publishCommand - Specifies publishing command which will be used to publish the package. Default: npm publish.
• publishTag - Specifies tag with which package will be published. See npm publish docs for more info. Default: latest.
• confirm - Ask for the confirmation before publishing. Default: true.

Validations

• uncommittedChanges - Check that there are no uncommitted changes in the working tree. Default: true.

• untrackedFiles - Check that there are no untracked files in the working tree. Default: true.

• gitTag - Check that git tag matches version specified in the package.json. Default: true.

• branch - Check that current branch matches the specified branch. Default: master.

  • You may also set the branch as a regular expression to be able to use publish-please in a multiple branches scenario like master and release:

    /(master|release)/

• sensitive and non essential Data - Perform audit for the sensitive data. Default: true if npm version is 5.9.0 or above, false otherwise.

  • sensitive and non-essential data are by default defined inside this .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.

• vulnerableDependencies - Perform vulnerable dependencies check using npm audit. Default: true if npm version is 6.1.0 or above, false otherwise.

  • 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

Running in dry mode

You can execute publish-please in dry mode by using the --dry-run option:

npm run publish-please --dry-run

Instead of publishing, this will show (after all validations) the content of the package that will be sent to npm, so that you can inspect it to be sure everything is there.

In this mode, the postPublishScript script will not run, since there is no publication to the registry.

It might be a good idea to add these two lines inside your .gitignore file:

package
*.tgz

Running publish-please with npx

You can execute publish-please directly with npx:

• Publish in a dry-run mode

npx publish-please --dry-run

• Safely publish to the npm registry

npx publish-please

• Setup a configuration file in order to customise the publishing workflow

npx publish-please config

Sensitive and non-essential data audit

Important note: tool provides some very basic sensitive data check. Do not rely on it fully. Always perform manual checks for the sensitive data in your packages.

Performed for the following items (see .sensitivedata file for more details):

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

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

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.
• pkgd - Get package publish info: package.json and file list.
• promisify-event - Promisify EventEmitter's event.

Author

Ivan Nikulin (ifaaan@gmail.com)