publish-please

    5.5.2 • Public • Published

    Publish, please!

    Safe and highly functional replacement for npm publish.

    Build Status npm version Dependency Status

    Publish-please enables you to :

    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:


    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:

    dry-run-demo-with-errors

    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

    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

    publish-demo-success

    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


    Author

    Ivan Nikulin (ifaaan@gmail.com)


    Maintainer

    Henri d'Orgeval

    Install

    npm i publish-please

    DownloadsWeekly Downloads

    4,619

    Version

    5.5.2

    License

    MIT

    Unpacked Size

    103 kB

    Total Files

    46

    Last publish

    Collaborators

    • inikulin
    • belym.a.2105
    • hdorgeval
    • rb3as