1 | # np [![Build Status](https://travis-ci.org/sindresorhus/np.svg?branch=master)](https://travis-ci.org/sindresorhus/np) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo)
|
2 |
|
3 | > A better `npm publish`
|
4 |
|
5 | <div>
|
6 | <br>
|
7 | <br>
|
8 | <a href="https://issuehunt.io">
|
9 | <img src="https://user-images.githubusercontent.com/170270/50307315-5c349200-0498-11e9-95bb-e51a8cfc2b15.png" width="600">
|
10 | </a>
|
11 | <br>
|
12 | <br>
|
13 | <br>
|
14 | </div>
|
15 |
|
16 | <img src="screenshot.gif" width="688">
|
17 |
|
18 |
|
19 | ## Why
|
20 |
|
21 | - [Interactive UI](#interactive-ui)
|
22 | - Ensures you are publishing from the `master` branch
|
23 | - Ensures the working directory is clean and that there are no unpulled changes
|
24 | - Reinstalls dependencies to ensure your project works with the latest dependency tree
|
25 | - Runs the tests
|
26 | - Bumps the version in package.json and npm-shrinkwrap.json (if present) and creates a git tag
|
27 | - Prevents [accidental publishing](https://github.com/npm/npm/issues/13248) of pre-release versions under the `latest` [dist-tag](https://docs.npmjs.com/cli/dist-tag)
|
28 | - Publishes the new version to npm, optionally under a dist-tag
|
29 | - Rolls back the project to its previous state in case publishing fails
|
30 | - Pushes commits and tags (newly & previously created) to GitHub/GitLab
|
31 | - Supports [two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication)
|
32 | - Enables two-factor authentication on new repositories
|
33 | <br>
|
34 | <sub>(does not apply to external registries)</sub>
|
35 | - Opens a prefilled GitHub Releases draft after publish
|
36 | - Warns about the possibility of extraneous files being published
|
37 |
|
38 |
|
39 | ## Prerequisite
|
40 |
|
41 | - Node.js 8 or later
|
42 | - npm 6.8.0 or later
|
43 | - Git 2.11 or later
|
44 |
|
45 |
|
46 | ## Install
|
47 |
|
48 | ```
|
49 | $ npm install --global np
|
50 | ```
|
51 |
|
52 |
|
53 | ## Usage
|
54 |
|
55 | ```
|
56 | $ np --help
|
57 |
|
58 | Usage
|
59 | $ np <version>
|
60 |
|
61 | Version can be:
|
62 | patch | minor | major | prepatch | preminor | premajor | prerelease | 1.2.3
|
63 |
|
64 | Options
|
65 | --any-branch Allow publishing from any branch
|
66 | --no-cleanup Skips cleanup of node_modules
|
67 | --no-tests Skips tests
|
68 | --yolo Skips cleanup and testing
|
69 | --no-publish Skips publishing
|
70 | --tag Publish under a given dist-tag
|
71 | --no-yarn Don't use Yarn
|
72 | --contents Subdirectory to publish
|
73 | --no-release-draft Skips opening a GitHub release draft
|
74 |
|
75 | Examples
|
76 | $ np
|
77 | $ np patch
|
78 | $ np 1.0.2
|
79 | $ np 1.0.2-beta.3 --tag=beta
|
80 | $ np 1.0.2-beta.3 --tag=beta --contents=dist
|
81 | ```
|
82 |
|
83 |
|
84 | ## Interactive UI
|
85 |
|
86 | Run `np` without arguments to launch the interactive UI that guides you through publishing a new version.
|
87 |
|
88 | <img src="screenshot-ui.png" width="1290">
|
89 |
|
90 |
|
91 | ## Config
|
92 |
|
93 | `np` can be configured both locally and globally. When using the global `np` binary, you can configure any of the CLI flags in either a `.np-config.js` or `.np-config.json` file in the home directory. When using the local `np` binary, for example, in a `npm run` script, you can configure `np` by setting the flags in either a top-level `np` field in `package.json` or in a `.np-config.js` or `.np-config.json` file in the project directory.
|
94 |
|
95 | Currently, these are the flags you can configure:
|
96 |
|
97 | - `anyBranch` - Allow publishing from any branch (`false` by default).
|
98 | - `cleanup` - Cleanup `node_modules` (`true` by default).
|
99 | - `tests` - Run `npm test` (`true` by default).
|
100 | - `yolo` - Skip cleanup and testing (`false` by default).
|
101 | - `publish` - Publish (`true` by default).
|
102 | - `tag` - Publish under a given dist-tag (`latest` by default).
|
103 | - `yarn` - Use yarn if possible (`true` by default).
|
104 | - `contents` - Subdirectory to publish (`.` by default).
|
105 | - `releaseDraft` - Open a GitHub release draft after releasing (`true` by default).
|
106 |
|
107 | For example, this configures `np` to never use Yarn and to use `dist` as the subdirectory to publish:
|
108 |
|
109 | `package.json`
|
110 | ```json
|
111 | {
|
112 | "name": "superb-package",
|
113 | "np": {
|
114 | "yarn": false,
|
115 | "contents": "dist"
|
116 | }
|
117 | }
|
118 | ```
|
119 |
|
120 | `.np-config.json`
|
121 | ```json
|
122 | {
|
123 | "yarn": false,
|
124 | "contents": "dist"
|
125 | }
|
126 | ```
|
127 |
|
128 | `.np-config.js`
|
129 | ```js
|
130 | module.exports = {
|
131 | yarn: false,
|
132 | contents: 'dist'
|
133 | };
|
134 | ```
|
135 |
|
136 | _**Note:** The global config only applies when using the global `np` binary, and is never inherited when using a local binary._
|
137 |
|
138 |
|
139 | ## Tips
|
140 |
|
141 | ### npm hooks
|
142 |
|
143 | You can use any of the test/version/publish related [npm lifecycle hooks](https://docs.npmjs.com/misc/scripts) in your package.json to add extra behavior.
|
144 |
|
145 | For example, here we build the documentation before tagging the release:
|
146 |
|
147 | ```json
|
148 | {
|
149 | "name": "my-awesome-package",
|
150 | "scripts": {
|
151 | "version": "./build-docs && git add docs"
|
152 | }
|
153 | }
|
154 | ```
|
155 |
|
156 | ### Release script
|
157 |
|
158 | You can also add `np` to a custom script in `package.json`. This can be useful if you want all maintainers of a package to release the same way (Not forgetting to push Git tags, for example). However, you can't use `publish` as name of your script because it's an [npm defined lifecycle hook](https://docs.npmjs.com/misc/scripts).
|
159 |
|
160 | ```json
|
161 | {
|
162 | "name": "my-awesome-package",
|
163 | "scripts": {
|
164 | "release": "np"
|
165 | },
|
166 | "devDependencies": {
|
167 | "np": "*"
|
168 | }
|
169 | }
|
170 | ```
|
171 |
|
172 | ### Signed Git tag
|
173 |
|
174 | Set the [`sign-git-tag`](https://docs.npmjs.com/misc/config#sign-git-tag) npm config to have the Git tag signed:
|
175 |
|
176 | ```
|
177 | $ npm config set sign-git-tag true
|
178 | ```
|
179 |
|
180 | Or set the [`version-sign-git-tag`](https://yarnpkg.com/lang/en/docs/cli/version/#toc-git-tags) Yarn config:
|
181 |
|
182 | ```
|
183 | $ yarn config set version-sign-git-tag true
|
184 | ```
|
185 |
|
186 | ### Private packages
|
187 |
|
188 | <img src="private-packages.png" width="260" align="right">
|
189 |
|
190 | You can use `np` for packages that aren't publicly published to npm (perhaps installed from a private git repo).
|
191 |
|
192 | Set `"private": true` in your `package.json` and the publish step will be skipped. All other steps
|
193 | including versioning and pushing tags will still be completed.
|
194 |
|
195 | ### Public scoped packages
|
196 |
|
197 | To publish [scoped packages](https://docs.npmjs.com/misc/scope#publishing-public-scoped-packages-to-the-public-npm-registry) to the public registry, you need to set the access level to `public`. You can do that by adding the following to your `package.json`:
|
198 |
|
199 | ```json
|
200 | "publishConfig": {
|
201 | "access": "public"
|
202 | }
|
203 | ```
|
204 |
|
205 | ### Publish to a custom registry
|
206 |
|
207 | Set the [`registry` option](https://docs.npmjs.com/misc/config#registry) in package.json to the URL of your registry:
|
208 |
|
209 | ```json
|
210 | "publishConfig":{
|
211 | "registry": "http://my-internal-registry.local"
|
212 | }
|
213 | ```
|
214 |
|
215 | ### Publish with a CI
|
216 |
|
217 | If you use a Continuous Integration server to publish your tagged commits, use the `--no-publish` flag to skip the publishing step of `np`.
|
218 |
|
219 | ### Publish to gh-pages
|
220 |
|
221 | To publish to `gh-pages` (or any other branch that serves your static assets), install [`branchsite`](https://github.com/enriquecaballero/branchsite), an `np`-like CLI tool aimed to complement `np`, and create an [npm "post" hook](https://docs.npmjs.com/misc/scripts) that runs after `np`.
|
222 |
|
223 | ```
|
224 | $ npm install --save-dev branchsite
|
225 | ```
|
226 |
|
227 | ```json
|
228 | "scripts":{
|
229 | "deploy": "np",
|
230 | "postdeploy": "bs"
|
231 | }
|
232 | ```
|
233 |
|
234 | ### Initial version
|
235 |
|
236 | For new packages, start the `version` field in package.json at `0.0.0` and let `np` bump it to `1.0.0` or `0.1.0` when publishing.
|
237 |
|
238 | ### Release an update to an old major version
|
239 |
|
240 | To release a minor/patch version for an old major version, create a branch from the major version's git tag and run `np`:
|
241 |
|
242 | ```console
|
243 | $ git checkout -b fix-old-bug v1.0.0 # Where 1.0.0 is the previous major version
|
244 | # Create some commits…
|
245 | $ git push --set-upstream origin HEAD
|
246 | $ np patch --any-branch --tag=v1
|
247 | ```
|
248 |
|
249 | ### Prerequisite step runs forever on macOS
|
250 |
|
251 | If you're using macOS Sierra 10.12.2 or later, your SSH key passphrase is no longer stored into the keychain by default. This may cause the `prerequisite` step to run forever because it prompts for your passphrase in the background. To fix this, add the following lines to your `~/.ssh/config` and run a simple Git command like `git fetch`.
|
252 |
|
253 | ```
|
254 | Host *
|
255 | AddKeysToAgent yes
|
256 | UseKeychain yes
|
257 | ```
|
258 |
|
259 | If you're running into other issues when using SSH, please consult [GitHub's support article](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
260 |
|
261 |
|
262 | ## Maintainers
|
263 |
|
264 | - [Sindre Sorhus](https://github.com/sindresorhus)
|
265 | - [Sam Verschueren](https://github.com/SamVerschueren)
|
266 | - [Itai Steinherz](https://github.com/itaisteinherz)
|