{"id":13483188,"url":"https://github.com/inikulin/publish-please","last_synced_at":"2025-05-15T08:11:36.222Z","repository":{"id":47335035,"uuid":"47348757","full_name":"inikulin/publish-please","owner":"inikulin","description":"Safe and highly functional replacement for `npm publish`.","archived":false,"fork":false,"pushed_at":"2024-08-24T04:21:01.000Z","size":3409,"stargazers_count":737,"open_issues_count":6,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-30T06:40:03.667Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inikulin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit.opts","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-03T17:36:48.000Z","updated_at":"2024-09-04T13:30:15.000Z","dependencies_parsed_at":"2024-10-27T13:02:44.292Z","dependency_job_id":"311bfa83-6058-4e0a-b9b6-5979728536e1","html_url":"https://github.com/inikulin/publish-please","commit_stats":{"total_commits":561,"total_committers":15,"mean_commits":37.4,"dds":0.4830659536541889,"last_synced_commit":"d90ef2fa2b2550900e273bd6fc979157f72f10b6"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inikulin%2Fpublish-please","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inikulin%2Fpublish-please/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inikulin%2Fpublish-please/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inikulin%2Fpublish-please/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inikulin","download_url":"https://codeload.github.com/inikulin/publish-please/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252601876,"owners_count":21774663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:08.923Z","updated_at":"2025-05-15T08:11:31.210Z","avatar_url":"https://github.com/inikulin.png","language":"JavaScript","funding_links":[],"categories":["Packages","JavaScript"],"sub_categories":["Publishing"],"readme":"# Publish, please!\nSafe and highly functional replacement for `npm publish`.\n\n[![Build Status](https://travis-ci.org/inikulin/publish-please.svg?branch=master)](https://travis-ci.org/inikulin/publish-please)\n[![npm version](https://img.shields.io/npm/v/publish-please.svg)](https://www.npmjs.com/package/publish-please)\n[![Dependency Status](https://david-dm.org/inikulin/publish-please.svg)](https://david-dm.org/inikulin/publish-please)\n\nPublish-please enables you to :\n- [Validate your package before publishing to the registry](#Validate-your-package-before-publishing-to-the-registry)\n- [Publish to the registry on sucessfull validation](#Publish-to-the-registry-on-sucessfull-validation)\n- [Run any script on successfull publishing](#Run-any-script-on-successfull-publishing)\n\nPublish-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.\n\nSee 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).\n\nOther topics:\n- [Installing publish-please locally](#Installing-publish-please-locally)\n- [Upgrading to latest publish-please version](#Upgrading-to-latest-publish-please-version)\n- [Running in CI mode](#Running-in-CI-mode)\n- [Customize the Validation Workflow](#Customize-the-Validation-Workflow)\n- [Customize the Publishing Workflow](#Customize-the-Publishing-Workflow)\n\n-------------------------------------------------------------\n## Validate your package before publishing to the registry\n\nThere are numerous ways to \"shoot yourself in the foot\" using `npm publish`. \n\n`publish-please` enables you to check that what will be sent to the registry is valid, free of vulnerabilities and free of useless files.\n\nBefore running `npm publish`,  run this command at the root of your project folder:\n\n```sh\nnpx publish-please --dry-run\n```\n\nThe following example shows that you are about to push your test files to the registry:\n\n![dry-run-demo-with-errors](media/dry-run-with-errors.gif)\n\nWhen 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:\n\n![dry-run-demo-success](media/dry-run-demo-success.gif)\n\n### **The Validation Workflow performs by default the following actions:**\n\n- **npm test**\n    - Check that all tests pass\n\n- **Checking for the vulnerable dependencies**\n    - Perform vulnerable dependencies check using `npm audit`\n\n- **Checking for the uncommitted changes**\n    - Check that there are no uncommitted changes in the working tree\n\n- **Checking for the untracked files**\n    - Check that there are no untracked files in the working tree\n\n- **Checking for the sensitive and non-essential data in the npm package**\n    - Check that the npm package will not embed sensitive files or useless files (like test files)\n\n- **Validating branch** \n    - Check that current branch is master\n\n- **Validating git tag**\n    - Check that git tag matches version specified in the `package.json`\n\n-------------------------------------------------------------\n## Customize the Validation Workflow\n\n- **npm test**\n    - you can run any kind of command in place of the `npm test` command. \n    For this you need a `.publishrc` configuration file at the root of your project. To create or modify the `.publishrc` file, run the command\n\n    ```sh\n    npx publish-please config\n\n    Do you want to run any scripts before publishing (e.g. build steps, tests)? Yes\n    Input pre-publish script: npm run my-own-script\n    ```\n\n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Do you want to run any scripts before publishing (e.g.  build steps, tests)? No\n        ```\n        or directly edit the property `prePublishScript` in the `.publishrc` file:\n\n        ```json\n        {\n            \"prePublishScript\": false,\n        }\n         ```\n\n\n- **Checking for the vulnerable dependencies**\n    - This validation check uses `npm audit` under the hood. This validation check performs only if npm version is 6.1.0 or above.\n\n    - 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:\n\n        ```yaml\n        https://npmjs.com/advisories/12\n        https://npmjs.com/advisories/577\n        ```\n    - you may perform vulnerabilities check only for a specific vulnerability level: `critical`, `high`, `moderate` or `low`. \n    To do this create an `audit.opts` file in the root of your project with content like the following:\n        ```sh\n        --audit-level=high\n        ```\n        The above example will enable to report only vulnerabilities of level `critical` and `high`\n\n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that your package doesn`t have vulnerable dependencies before publishing? No\n        ```\n\n        or directly edit the property `vulnerableDependencies` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"vulnerableDependencies\": false,\n            }\n        }\n         ```\n\n- **Checking for the uncommitted changes**\n    - This validation checks that there are no uncommitted changes in the working tree.\n    \n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that there are no uncommitted changes in your working tree before publishing? No\n        ```\n\n        or directly edit the property `uncommittedChanges` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"uncommittedChanges\": false,\n            }\n        }\n         ```\n\n- **Checking for the untracked files**\n    - This validation checks that there are no untracked files in the working tree.\n\n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that there are no files that are not tracked by git in your working tree before publishing? No\n        ```\n\n        or directly edit the property `untrackedFiles` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"untrackedFiles\": false,\n            }\n        }\n         ```\n\n- **Checking for the sensitive and non-essential data in the npm package**\n    - 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.\n\n    - This validation is able to detect the following files:\n        - Benchmark files\n        - Configuration files\n           - CI\n           - eslint\n           - GitHub\n           - JetBrains\n           - Visual Studio Code\n        - Coverage files\n        - Demo files\n        - Dependency directories\n        - Doc files\n        - Example files\n        - Log files\n        - Private SSH key\n        - Script files\n        - Secret files\n        - Source files\n        - Temp files\n        - Test files\n        - Zip files\n           - Output of 'npm pack'\n\n    - sensitive and non-essential files are defined inside this built-in [.sensitivedata](.sensitivedata) file.\n\n    - you may completely override this file by creating a `.sensitivedata` file in the root of your project so that this validation fits your needs.\n        - if you create your own `.sensitivedata` file, and the `package.json` file has no `files` section, consider adding `.sensitivedata` to the `.npmignore` file.\n\n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that there is no sensitive and non-essential data in the npm package? No\n        ```\n\n        or directly edit the property `sensitiveData` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"sensitiveData\": false,\n            }\n        }\n         ```\n\n- **Validating branch**\n    - This validation checks that current branch is `master`.\n    - 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`:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that you are publishing from the correct git branch? Yes\n        Which branch should it be? /(master|release)/\n        ```\n\n        or directly edit the property `branch` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"branch\": \"/(master|release)/\",\n            }\n        }\n         ```\n    \n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that you are publishing from the correct git branch? No\n        ```\n\n        or directly edit the property `branch` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"branch\": false,\n            }\n        }\n         ```\n\n- **Validating git tag**\n    - This validation checks that git tag matches version specified in the `package.json`.\n    - if you want to disable this validation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Would you like to verify that published commit has git tag that is equal to the version specified in package.json? No\n        ```\n\n        or directly edit the property `gitTag` in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"gitTag\": false,\n            }\n        }\n         ```\n\n    - if the git tag contains a prefix to the version like for example `foo-v0.0.42`, supply the prefix in the `.publishrc` file:\n\n        ```json\n        {\n            \"validations\": {\n                \"gitTag\": \"foo-v\",\n            }\n        }\n        ```\n\n-------------------------------------------------------------\n## Publish to the registry on sucessfull validation\n\nTo publish on successfull validation, run the following command:\n\n```sh\nnpx publish-please\n```\n![publish-demo-success](media/publish-demo-success.gif)\n\n## Customize the Publishing Workflow\n\n- **publish command**\n\n    You can customize the command used by publish-please to publish to the registry. By default this command is `npm publish`.\n    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)). \n    \n    You may also want to run your own publish script instead of the `npm publish`command.\n\n    ```sh\n    npx publish-please config\n\n    Specify publishing command which will be used to publish your package: \n    npm publish --userconfig ~/.npmrc-myuser-config \n    ```\n    or directly edit the property `publishCommand` in the `.publishrc` file:\n    ```json\n    {\n        \"publishCommand\": \"npm publish --userconfig ~/.npmrc-myuser-config\"\n    }\n     ```\n\n- **publish Tag**\n\n    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.\n    By default publish please will run the `npm publish` command with the option `--tag latest`.\n\n    When you want to manually release an alpha version for version `x.y.z` on npm, you should take the following steps:\n    - in package.json: bump version to `x.y.z-alpha.1`, \n    - commit and push;\n    - on github: tag this commit with `vx.y.z-alpha.1`\n    - in the `.publishrc` file edit the `publishTag` property:\n\n        ```json\n        {\n            \"publishTag\": \"alpha\"\n        }\n        ```\n\n    - run publish-please (publish-please will automatically add on the publish command the option `--tag alpha`):\n\n        ```sh\n        npx publish-please\n        ```\n\n        or\n\n        ```sh\n        npm run publish-please\n        ```\n        if you have installed locally publish-please\n\n- **confirm** \n\n    - by default a confirmation will be asked before publishing.\n    - if you want to disable this confirmation, run the command:\n\n        ```sh\n        npx publish-please config\n\n        Do you want manually confirm publishing? No\n        ```\n\n        or directly edit the property `confirm` in the `.publishrc` file:\n\n        ```json\n        {\n            \"confirm\": false\n        }\n        ```\n\n-------------------------------------------------------------\n## Run any script on successfull publishing\n\n- Publish-please enables you to run a command after successful publishing. Use it for release announcements, uploading binaries, etc.\n\n- to configure a post-publish script:\n\n    ```sh\n    npx publish-please config\n\n    Do you want to run any scripts after succesful publishing (e.g. releaseannouncements, binary uploading)? Yes\n    Input post-publish script : npm run my-post-publish-script\n    ```\n    or directly edit the property `postPublishScript` in the `.publishrc` file:\n    ```json\n    {\n        \"postPublishScript\": \"npm run my-post-publish-script\"\n    }\n    ```\n\n- to disable a post-publish script:\n    ```sh\n    npx publish-please config\n\n    Do you want to run any scripts after succesful publishing (e.g. releaseannouncements, binary uploading)? No\n    ```\n    or directly edit the property `postPublishScript` in the `.publishrc` file:\n    ```json\n    {\n        \"postPublishScript\": \"\"\n    }\n    ```\n\n-------------------------------------------------------------\n## Upgrading to latest publish-please version\n\n- 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. \n\n- Run `npm help scripts` to get more details.\n\n-------------------------------------------------------------\n## Running in CI mode\n\nYou can execute publish-please in CI mode by adding the `--ci` option:\n\n```sh\nnpm run publish-please --ci\n```\n\nor \n\n```sh\nnpx publish-please --ci\n```\n\nThis option will turn off the default elegant-status reporter in favor of the built-in CI reporter.\nUse this option to disable emoji and spinner usage.\nWhen publish-please executes in a CI (Teamcity, Travis, AppVeyor, ...), the CI reporter is automatically activated.\n\n-------------------------------------------------------------\n## Installing publish-please locally\n\npublish-please can be installed locally:\n\n```sh\nnpm install --save-dev publish-please\n```\n\nOnce installed, the configuration wizard will enable you to configure the validation and publishing workflow.\n\n**From now on you cannot use anymore the `npm publish` command in your project.**\n\nBut 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`:\n\n```sh\nnpm run publish-please\n```\n\n-------------------------------------------------------------\n## Check out my other packages used by this tool\n- [cp-sugar](https://github.com/inikulin/cp-sugar) - Some sugar for child_process module.\n- [elegant-status](https://github.com/inikulin/elegant-status) - Create elegant task status for CLI.\n\n-------------------------------------------------------------\n## Author\n[Ivan Nikulin](https://github.com/inikulin) (ifaaan@gmail.com)\n\n-------------------------------------------------------------\n## Maintainer\n[Henri d'Orgeval](https://github.com/hdorgeval)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finikulin%2Fpublish-please","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finikulin%2Fpublish-please","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finikulin%2Fpublish-please/lists"}