@anizoptera/publish-clean 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +151 -216
- package/dist/cli.js +449 -294
- package/package.json +3 -8
package/README.md
CHANGED
|
@@ -1,23 +1,21 @@
|
|
|
1
1
|
# @anizoptera/publish-clean
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pre-publish npm package cleaner that strips common useless noise and crap from
|
|
4
|
+
`package.json`; prevents accidental publication of unwanted things and unresolved
|
|
5
|
+
dependencies. No deps, one JS file.
|
|
5
6
|
|
|
6
7
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean)
|
|
7
8
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
|
|
8
9
|
[](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
|
|
9
|
-
[](package.json)
|
|
11
11
|
[](package.json)
|
|
12
|
-
[](https://pnpm.io/cli/pack)
|
|
14
|
-
[](https://bun.sh/docs/cli/test)
|
|
12
|
+
[](LICENSE)
|
|
15
13
|
|
|
16
14
|
When you run `npm publish`, two things ship that you probably did not mean to ship.
|
|
17
15
|
|
|
18
|
-
The first is your `package.json`. It is a development manifest
|
|
19
|
-
|
|
20
|
-
|
|
16
|
+
The first is your `package.json`. It is a development manifest: devDependencies, config
|
|
17
|
+
blocks for your test runner, linter and formatter, `packageManager`, `workspaces`, `pnpm`
|
|
18
|
+
settings, release-tool settings, and every script you run locally.
|
|
21
19
|
npm sends all of it, unchanged, to everyone who installs your package. In a pnpm
|
|
22
20
|
workspace it can also send `workspace:*` and `catalog:` specs that were never resolved,
|
|
23
21
|
and those break the install for every consumer.
|
|
@@ -27,20 +25,29 @@ tests, `.github/`, a lockfile. You do not see the tarball before it goes out, an
|
|
|
27
25
|
version is published you cannot edit it. Unpublishing only works for a short window and
|
|
28
26
|
under conditions npm decides.
|
|
29
27
|
|
|
30
|
-
`publish-clean` packs the package, rewrites the
|
|
31
|
-
what consumers actually use,
|
|
32
|
-
never modified. If the artifact still has something in it that should
|
|
33
|
-
declares a `main`, `exports`, or `bin` path that is not in the tarball, it
|
|
34
|
-
of publishing.
|
|
28
|
+
`publish-clean` packs the package once, rewrites the `package.json` inside that tarball
|
|
29
|
+
down to what consumers actually use, checks the result, and publishes those exact bytes.
|
|
30
|
+
Your working tree is never modified. If the artifact still has something in it that should
|
|
31
|
+
not ship, or declares a `main`, `exports`, or `bin` path that is not in the tarball, it
|
|
32
|
+
fails instead of publishing.
|
|
35
33
|
|
|
36
|
-
It
|
|
37
|
-
|
|
34
|
+
It packs with pnpm and publishes with npm, and cleans the manifest in between. Both
|
|
35
|
+
choices are argued, with measurements, in
|
|
36
|
+
[why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
38
37
|
|
|
39
38
|
## Install
|
|
40
39
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
40
|
+
| Project | Install | Run |
|
|
41
|
+
| ------- | --------------------------------------- | ------------------------- |
|
|
42
|
+
| pnpm | `pnpm add -D @anizoptera/publish-clean` | `pnpm exec publish-clean` |
|
|
43
|
+
| Bun | `bun add -d @anizoptera/publish-clean` | `bunx publish-clean` |
|
|
44
|
+
| npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
|
|
45
|
+
| Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
|
|
46
|
+
|
|
47
|
+
**Whatever you start it with, `pnpm` prepares the package and `npm` uploads it, so both
|
|
48
|
+
must be on `PATH`.** A Bun, npm or Yarn project needs pnpm installed too, including in CI.
|
|
49
|
+
|
|
50
|
+
Also needs `tar` and Node.js 22.14+. Below 22.14 npm cannot mint provenance.
|
|
44
51
|
|
|
45
52
|
That installs one package and nothing else. `publish-clean` has zero runtime
|
|
46
53
|
dependencies: it is a single file that talks to `pnpm`, `npm` and `tar` through the
|
|
@@ -48,29 +55,20 @@ tools you already have. For something that sits on your publish path and handles
|
|
|
48
55
|
registry credentials, that matters. A publishing tool with a dependency tree is a
|
|
49
56
|
supply-chain risk of its own, and this one has no transitive code to audit.
|
|
50
57
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`--provenance` also needs Node.js 22.14+, npm 11.5.1+, and a cloud CI runner. npm will
|
|
54
|
-
not sign a publish that came from your laptop.
|
|
58
|
+
`--provenance` additionally needs npm 11.5.1+ and a cloud CI runner. npm will not sign a
|
|
59
|
+
publish that came from your laptop.
|
|
55
60
|
|
|
56
61
|
## Package managers
|
|
57
62
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
| Your project | How to run it | What to expect |
|
|
63
|
-
| ------------ | ------------------------- | --------------------------------------------------------- |
|
|
64
|
-
| pnpm | `pnpm exec publish-clean` | Everything works, no warning. |
|
|
65
|
-
| npm | `npm exec publish-clean` | Works. Prints an advisory that packing goes through pnpm. |
|
|
66
|
-
| Yarn | `yarn publish-clean` | Same as npm. |
|
|
67
|
-
| Bun | `bunx publish-clean` | Same as npm. |
|
|
63
|
+
Why pnpm packs and npm publishes: pnpm is the only packer that resolves every workspace
|
|
64
|
+
layout correctly, and npm is the only client that can sign a release. The measurements are
|
|
65
|
+
in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
68
66
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
67
|
+
Started with anything other than pnpm, it prints an advisory on stderr saying so. That is
|
|
68
|
+
a warning, not an error. Nothing behaves differently because of it, and there is no flag
|
|
69
|
+
to silence it.
|
|
72
70
|
|
|
73
|
-
For a single package
|
|
71
|
+
For a single package every manager behaves the same, since nothing in the manifest needs
|
|
74
72
|
resolving before it ships.
|
|
75
73
|
|
|
76
74
|
Monorepos are where it matters. `pnpm pack` resolves `workspace:` and `catalog:` specs by
|
|
@@ -159,8 +157,8 @@ publishes its own tarball, so you get the checks and not the cleaned manifest.
|
|
|
159
157
|
pnpm exec publish-clean --dry-run
|
|
160
158
|
```
|
|
161
159
|
|
|
162
|
-
Prints
|
|
163
|
-
|
|
160
|
+
Prints every file that would ship and the cleaned `package.json`, then deletes its temp
|
|
161
|
+
tree. Add `--tarball-out DIR` to keep the tarball itself.
|
|
164
162
|
|
|
165
163
|
### Publishing a restricted package
|
|
166
164
|
|
|
@@ -181,164 +179,109 @@ publish-clean packages/my-lib -- --access public --tag next
|
|
|
181
179
|
|
|
182
180
|
```mermaid
|
|
183
181
|
flowchart TD
|
|
184
|
-
A[Your package directory] -->|pnpm pack| B[Tarball
|
|
185
|
-
B --> C[
|
|
186
|
-
C --> D
|
|
187
|
-
D --> E
|
|
188
|
-
E
|
|
189
|
-
|
|
190
|
-
G --> H{Same files, same manifest, still no leaks?}
|
|
191
|
-
H --> I[npm publish tarball 2]
|
|
182
|
+
A[Your package directory] -->|pnpm pack| B[Tarball, file set chosen by pnpm]
|
|
183
|
+
B --> C[Copy it, rewriting only the package.json inside]
|
|
184
|
+
C --> D[Final tarball]
|
|
185
|
+
D --> E{Checks, all reading this tarball}
|
|
186
|
+
E -->|any fails| F[Exit non-zero, publish nothing]
|
|
187
|
+
E -->|all pass| G[npm publish this same tarball]
|
|
192
188
|
```
|
|
193
189
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
## Why it works this way
|
|
198
|
-
|
|
199
|
-
### Why pnpm does the packing
|
|
200
|
-
|
|
201
|
-
Not for file selection. pnpm, npm and Bun pick the same files: same `files` field, same
|
|
202
|
-
`.npmignore`, same packlist defaults. There are no file rules of this tool's own either,
|
|
203
|
-
so that part behaves however your package manager already behaves.
|
|
190
|
+
The checks are listed under [What it checks](#what-it-checks). The point of the shape is
|
|
191
|
+
that they all read the tarball that gets uploaded, so what passed the checks and what
|
|
192
|
+
reached the registry are the same bytes, not two things that ought to match.
|
|
204
193
|
|
|
205
|
-
|
|
206
|
-
"whatever version of that package is in this repo right now". It has to become a real
|
|
207
|
-
version range before it ships, because to a stranger installing from the registry
|
|
208
|
-
`workspace:*` means nothing.
|
|
194
|
+
`--dry-run` and `--guard-only` run the whole pipeline and stop before the publish.
|
|
209
195
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
```
|
|
213
|
-
npm error code EUNSUPPORTEDPROTOCOL
|
|
214
|
-
npm error Unsupported URL Type "workspace:": workspace:*
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
`npm pack` on that same package exits 0 and writes `workspace:*` straight into the
|
|
218
|
-
tarball. It neither resolves it nor refuses it, and silently publishing something you
|
|
219
|
-
can't install is the one behaviour a release tool can't be built on.
|
|
220
|
-
|
|
221
|
-
pnpm and Bun both resolve it, and both stop loudly when they can't. Their output matches
|
|
222
|
-
down to `workspace:^` and `workspace:~` in `peerDependencies` and `optionalDependencies`,
|
|
223
|
-
and `catalog:` entries too. On correctness there is nothing to choose between them.
|
|
224
|
-
|
|
225
|
-
### Why pnpm rather than Bun
|
|
226
|
-
|
|
227
|
-
They resolve from different places, and that decides it.
|
|
228
|
-
|
|
229
|
-
pnpm looks for the dependency in the packing package's own `node_modules` and resolves it
|
|
230
|
-
from there. It never asks who put it there, so a Bun workspace, which gives every package
|
|
231
|
-
its own `node_modules`, packs as readily as pnpm's own. Yarn hoists to the root instead
|
|
232
|
-
and needs the one-time setup above.
|
|
233
|
-
|
|
234
|
-
Bun reads `bun.lock`. It resolves the workspaces Bun installed and refuses the others:
|
|
235
|
-
|
|
236
|
-
```
|
|
237
|
-
error: Failed to resolve workspace version for "@acme/utils" in `dependencies`.
|
|
238
|
-
Run `bun install` and try again.
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
That message is accurate and useless, because in a pnpm repo `bun install` is not
|
|
242
|
-
something you want to be told to run. A tool that executes in other people's
|
|
243
|
-
repositories has to cope with the repository it finds, so it packs with the one that
|
|
244
|
-
reads all of them.
|
|
245
|
-
|
|
246
|
-
There's a correctness gap too, and it's the quiet kind. An aliased workspace dependency,
|
|
247
|
-
`"utils": "workspace:@acme/utils@*"`, has to come out the other side as an npm alias.
|
|
248
|
-
pnpm writes `"npm:@acme/utils@1.2.3"`. Bun 1.3.14 writes `"@acme/utils@*"`: the `npm:`
|
|
249
|
-
prefix is dropped and the range was never resolved. npm won't take it.
|
|
250
|
-
|
|
251
|
-
```
|
|
252
|
-
npm error code EINVALIDTAGNAME
|
|
253
|
-
npm error Invalid tag name "is-odd@3.0.1" of package "aliased@is-odd@3.0.1"
|
|
254
|
-
```
|
|
196
|
+
## Why it works this way
|
|
255
197
|
|
|
256
|
-
|
|
257
|
-
release.
|
|
198
|
+
### Why pnpm packs, and npm publishes
|
|
258
199
|
|
|
259
|
-
|
|
260
|
-
|
|
200
|
+
pnpm because of workspaces. A dependency written `"@acme/utils": "workspace:*"` has to
|
|
201
|
+
become a real version range before it ships, and pnpm is the only packer that does that
|
|
202
|
+
for every layout it might find, including a Bun one. npm writes `workspace:*` into the
|
|
203
|
+
tarball unchanged and exits 0, publishing a package nobody can install. Bun resolves only
|
|
204
|
+
what Bun installed, and quietly mangles an aliased workspace dependency.
|
|
261
205
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
206
|
+
npm because of provenance. The signed attestation behind the "Built and signed on GitHub
|
|
207
|
+
Actions" badge is minted by the npm CLI talking to Sigstore, and trusted publishing, which
|
|
208
|
+
removes the long-lived token entirely, is npm's own exchange with the registry. No other
|
|
209
|
+
client does either one. `npm publish` also takes a tarball directly, which is what the
|
|
210
|
+
packing step already produced.
|
|
267
211
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
`workspace:1.2.3` ranges, named catalogs, and refusing a catalog entry that doesn't exist.
|
|
212
|
+
The measurements behind both choices, and the one thing packing with pnpm costs you, are
|
|
213
|
+
in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
271
214
|
|
|
272
215
|
### Why the manifest is cleaned on a copy
|
|
273
216
|
|
|
274
|
-
The
|
|
275
|
-
is never touched.
|
|
217
|
+
The manifest is read out of the packed tarball and written back into a copy of it, in a
|
|
218
|
+
temp directory. Your working tree is never touched.
|
|
276
219
|
|
|
277
220
|
The obvious alternative is what a lot of hand-rolled release scripts do: edit
|
|
278
221
|
`package.json`, publish, edit it back. That's fine until something dies in the middle,
|
|
279
222
|
and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
|
|
280
223
|
twice at once. Cleaning a copy has neither problem and costs a directory in `/tmp`.
|
|
281
224
|
|
|
282
|
-
### Why
|
|
225
|
+
### Why the tarball is edited instead of packed again
|
|
283
226
|
|
|
284
227
|
Give npm a directory and it packs during the upload, so the bytes that reach the registry
|
|
285
|
-
only come into existence after the last check has run.
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
`npm publish` also takes a tarball directly, which is exactly what the previous step
|
|
310
|
-
produced.
|
|
228
|
+
only come into existence after the last check has run. Packing first means they exist
|
|
229
|
+
before anything is uploaded: they can be listed, scanned for leaks, kept with
|
|
230
|
+
`--tarball-out` for a build attestation, and then published as themselves. What you
|
|
231
|
+
inspect is what ships.
|
|
232
|
+
|
|
233
|
+
So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
|
|
234
|
+
to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
|
|
235
|
+
cleaning removes it, because it is useless to anyone installing the package. A second pack
|
|
236
|
+
then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
|
|
237
|
+
exclusion, and quietly drops files the first pack included. A package shipping a
|
|
238
|
+
`.gitignore` that excludes any other shipped file loses it.
|
|
239
|
+
|
|
240
|
+
Editing avoids the question. Only the `package/package.json` member is replaced. Every
|
|
241
|
+
other entry is copied without being decoded, so the file set stays exactly what pnpm chose,
|
|
242
|
+
and entry shapes this tool does not model (pax headers for long paths, prefix splitting)
|
|
243
|
+
pass through untouched. It also keeps pnpm's normalised metadata: owner `0:0`, a fixed
|
|
244
|
+
timestamp, mode 644. A plain `tar` invocation would replace those with whatever the build
|
|
245
|
+
machine happens to have.
|
|
246
|
+
|
|
247
|
+
Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
|
|
248
|
+
`prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
|
|
249
|
+
npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
|
|
250
|
+
nothing can alter the artifact after it was checked.
|
|
311
251
|
|
|
312
252
|
## What it checks
|
|
313
253
|
|
|
314
|
-
`publish-clean`
|
|
315
|
-
|
|
316
|
-
- the package is `private: true`
|
|
317
|
-
- the
|
|
318
|
-
- the package has no non-empty `files` array
|
|
319
|
-
- the tarball
|
|
320
|
-
`node_modules`, or private
|
|
321
|
-
- dependency
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
Leak checks cannot be turned off by any flag or config key.
|
|
254
|
+
`publish-clean` stops, and publishes nothing, when:
|
|
255
|
+
|
|
256
|
+
- the package is marked `private: true`
|
|
257
|
+
- the working tree has uncommitted changes (`--no-git-checks` to allow it)
|
|
258
|
+
- the package has no non-empty `files` array (`--skip-file-check` to allow it)
|
|
259
|
+
- the tarball holds something that should never ship: a `.env`, an `.npmrc`, `.git`,
|
|
260
|
+
`node_modules`, or a private key. This one has no off switch, by any flag or config key
|
|
261
|
+
- a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, which
|
|
262
|
+
nobody outside your repo can install
|
|
263
|
+
- the manifest points `exports`, `types`, `main`, `browser`, `bin` or `sideEffects` at a
|
|
264
|
+
path that is not in the tarball
|
|
265
|
+
- rewriting the manifest changed anything else in the tarball
|
|
266
|
+
- you asked for `--provenance` from GitHub Actions, but the `repository` in your manifest
|
|
267
|
+
is not the repository the workflow is running in
|
|
268
|
+
|
|
269
|
+
It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm. The
|
|
270
|
+
packing still goes through pnpm, but the warning is there because the rest of your release
|
|
271
|
+
probably should too.
|
|
333
272
|
|
|
334
273
|
## What the cleaned manifest keeps
|
|
335
274
|
|
|
336
275
|
Everything a consumer or a registry reads survives: `name`, `version`, `license`,
|
|
337
276
|
`dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
|
|
338
|
-
`bin`, `
|
|
339
|
-
|
|
277
|
+
`bin`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of the public
|
|
278
|
+
surface.
|
|
340
279
|
|
|
341
|
-
|
|
280
|
+
`files` goes, because it is spent: it told the packer what to include, the tarball already
|
|
281
|
+
exists, nothing re-selects afterwards, and an install extracts every entry unfiltered. npm
|
|
282
|
+
agrees — its registry drops the field from the metadata it serves.
|
|
283
|
+
|
|
284
|
+
What else goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
|
|
342
285
|
`resolutions`, and the config blocks belonging to test runners, linters, formatters,
|
|
343
286
|
coverage tools, build systems and release tools. Scripts go too, apart from the install
|
|
344
287
|
lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
|
|
@@ -362,34 +305,14 @@ hear about it from a stranger's broken build rather than from your own release.
|
|
|
362
305
|
Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
|
|
363
306
|
would ship instead of trusting this list.
|
|
364
307
|
|
|
365
|
-
## Options
|
|
308
|
+
## Options and config
|
|
366
309
|
|
|
367
310
|
```bash
|
|
368
311
|
publish-clean [options] [package-dir] [-- npm-publish-args]
|
|
369
312
|
```
|
|
370
313
|
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
- `--guard-only`: run the full pack, clean, and final-tarball guard without
|
|
374
|
-
publishing.
|
|
375
|
-
- `--registry URL`: set `publishConfig.registry` on the cleaned manifest.
|
|
376
|
-
- `--skip-file-check`: skip suspicious-file checks and the required `files`
|
|
377
|
-
array check. Critical leak checks still run.
|
|
378
|
-
- `--no-git-checks`: skip the source git cleanliness check.
|
|
379
|
-
- `--tarball-out DIR`: copy the final tarball into `DIR` before publishing. The bytes
|
|
380
|
-
kept are the ones that were published, so a release pipeline can attach them to a
|
|
381
|
-
GitHub Release or sign them with build-provenance attestation.
|
|
382
|
-
- `-h`, `--help`: print usage.
|
|
383
|
-
|
|
384
|
-
Arguments after `--` go to `npm publish`, which publishes the final cleaned
|
|
385
|
-
tarball.
|
|
386
|
-
|
|
387
|
-
Pass the npm dist-tag explicitly. For normal public releases, use
|
|
388
|
-
`--tag latest`.
|
|
389
|
-
|
|
390
|
-
## Package config
|
|
391
|
-
|
|
392
|
-
Stable project defaults can live in `package.json`:
|
|
314
|
+
Most settings can be a flag or a `package.json` key. Flags win, so keep per-release
|
|
315
|
+
choices like dist-tags on the command line and stable project policy in the manifest:
|
|
393
316
|
|
|
394
317
|
```json
|
|
395
318
|
{
|
|
@@ -403,35 +326,49 @@ Stable project defaults can live in `package.json`:
|
|
|
403
326
|
}
|
|
404
327
|
```
|
|
405
328
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
329
|
+
| Flag | `package.json` | What it does |
|
|
330
|
+
| ------------------- | --------------- | ------------------------------------------------------------------------------------------ |
|
|
331
|
+
| `--dry-run` | - | Run everything up to the publish, then print the file list and the cleaned `package.json`. |
|
|
332
|
+
| `--guard-only` | - | Run everything up to the publish and exit, printing nothing. |
|
|
333
|
+
| `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
|
|
334
|
+
| `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
|
|
335
|
+
| `--skip-file-check` | `skipFileCheck` | Drop the suspicious-file check and the required `files` array. |
|
|
336
|
+
| `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
|
|
337
|
+
| - | `devFields` | Extra manifest fields to strip. |
|
|
338
|
+
| - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
|
|
339
|
+
| `-h`, `--help` | - | Print usage. |
|
|
340
|
+
|
|
341
|
+
Arguments after `--` go to `npm publish`. Pass the dist-tag explicitly: `--tag latest` for
|
|
342
|
+
a normal public release.
|
|
409
343
|
|
|
410
|
-
|
|
411
|
-
Leak checks keep running; those cannot be turned off.
|
|
344
|
+
A few of these deserve a sentence more.
|
|
412
345
|
|
|
413
|
-
`
|
|
414
|
-
|
|
346
|
+
`--tarball-out` keeps the bytes that were published, so a release pipeline can attach them
|
|
347
|
+
to a GitHub Release or sign them with build-provenance attestation. The copy happens in
|
|
348
|
+
every mode, before the publish, so you get the validated artifact even if the upload fails.
|
|
415
349
|
|
|
416
|
-
`
|
|
417
|
-
|
|
418
|
-
the dependency maps, are rejected here, so a typo cannot quietly break your package.
|
|
350
|
+
`registry` pins where the package goes, so it cannot end up on whatever registry the
|
|
351
|
+
machine happens to be pointed at.
|
|
419
352
|
|
|
420
|
-
`
|
|
421
|
-
package, stop mentioning it. A VS Code extension needs `contributes` and `publisher` in
|
|
422
|
-
the artifact to work, and no generic publishing tool is ever going to know that.
|
|
353
|
+
`skipFileCheck` does not touch the leak checks.
|
|
423
354
|
|
|
424
|
-
|
|
425
|
-
|
|
355
|
+
`noGitChecks` is what you need when you publish from a build directory, or from a checkout
|
|
356
|
+
that is not a git repository at all.
|
|
357
|
+
|
|
358
|
+
`devFields` refuses fields that npm or your consumers actually read, like `exports`, `bin`,
|
|
359
|
+
`engines` and the dependency maps, so a typo cannot quietly break your package.
|
|
360
|
+
|
|
361
|
+
`keepFields` answers the unrecognised-field report the other way: the field belongs in the
|
|
362
|
+
published package, stop mentioning it. A VS Code extension needs `contributes` and
|
|
363
|
+
`publisher` in the artifact to work, and no generic publishing tool is ever going to know
|
|
364
|
+
that.
|
|
426
365
|
|
|
427
366
|
## What it does not do
|
|
428
367
|
|
|
429
368
|
It isn't a release manager. It won't pick your version number, write a changelog, tag
|
|
430
|
-
anything, push a commit, create a GitHub release, or set up trusted publishing for you.
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
Pick a release manager and a validator to go with it. The next section covers which.
|
|
369
|
+
anything, push a commit, create a GitHub release, or set up trusted publishing for you. It
|
|
370
|
+
also doesn't check that your entry points resolve correctly for consumers. Pair it with a
|
|
371
|
+
release manager and a validator; the next section names them.
|
|
435
372
|
|
|
436
373
|
It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
|
|
437
374
|
than copying them, so it has nothing to bundle and refuses:
|
|
@@ -442,9 +379,7 @@ Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
|
|
|
442
379
|
|
|
443
380
|
Doing what it says makes the package publishable again. This is the one thing you give up
|
|
444
381
|
by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
|
|
445
|
-
is loud and tells you the fix.
|
|
446
|
-
neither bundles anything for a package inside a workspace, because the dependency hoists
|
|
447
|
-
to the workspace root where the package can't see it.
|
|
382
|
+
is loud and tells you the fix.
|
|
448
383
|
|
|
449
384
|
## How it compares
|
|
450
385
|
|