@anizoptera/publish-clean 0.2.0 → 0.4.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 +402 -158
- package/dist/cli.js +435 -169
- package/package.json +7 -8
package/README.md
CHANGED
|
@@ -1,121 +1,378 @@
|
|
|
1
1
|
# @anizoptera/publish-clean
|
|
2
2
|
|
|
3
|
+
Publish npm packages with a consumer-only `package.json`. Refuses to ship a `.env`, a
|
|
4
|
+
private key, or an unresolved workspace dependency.
|
|
5
|
+
|
|
3
6
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean)
|
|
7
|
+
[](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
|
|
4
8
|
[](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
[](package.json)
|
|
5
12
|
[](package.json)
|
|
6
13
|
[](https://pnpm.io/cli/pack)
|
|
7
14
|
[](https://bun.sh/docs/cli/test)
|
|
8
|
-
[](package.json)
|
|
9
|
-
[](LICENSE)
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
When you run `npm publish`, two things ship that you probably did not mean to ship.
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
|
|
18
|
+
The first is your `package.json`. It is a development manifest. It lists devDependencies,
|
|
19
|
+
config blocks for your test runner and linter and formatter, `packageManager`,
|
|
20
|
+
`workspaces`, `pnpm` settings, release-tool settings, and every script you run locally.
|
|
21
|
+
npm sends all of it, unchanged, to everyone who installs your package. In a pnpm
|
|
22
|
+
workspace it can also send `workspace:*` and `catalog:` specs that were never resolved,
|
|
23
|
+
and those break the install for every consumer.
|
|
15
24
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
25
|
+
The second is files. A `.env`, an `.npmrc` with a token in it, a stray `.pem`, your
|
|
26
|
+
tests, `.github/`, a lockfile. You do not see the tarball before it goes out, and once a
|
|
27
|
+
version is published you cannot edit it. Unpublishing only works for a short window and
|
|
28
|
+
under conditions npm decides.
|
|
20
29
|
|
|
21
|
-
|
|
30
|
+
`publish-clean` packs the package, rewrites the manifest of the extracted copy down to
|
|
31
|
+
what consumers actually use, packs that, and publishes the result. Your working tree is
|
|
32
|
+
never modified. If the artifact still has something in it that should not ship, or
|
|
33
|
+
declares a `main`, `exports`, or `bin` path that is not in the tarball, it fails instead
|
|
34
|
+
of publishing.
|
|
22
35
|
|
|
23
|
-
|
|
36
|
+
It uses pnpm to pack and npm to publish, and cleans the manifest in between. The
|
|
37
|
+
reasoning behind that is in [Why it works this way](#why-it-works-this-way).
|
|
24
38
|
|
|
25
|
-
|
|
26
|
-
catalog behavior in a way generic cleanup scripts usually do not.
|
|
39
|
+
## Install
|
|
27
40
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
41
|
+
```bash
|
|
42
|
+
pnpm add -D @anizoptera/publish-clean
|
|
43
|
+
```
|
|
31
44
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
45
|
+
That installs one package and nothing else. `publish-clean` has zero runtime
|
|
46
|
+
dependencies: it is a single file that talks to `pnpm`, `npm` and `tar` through the
|
|
47
|
+
tools you already have. For something that sits on your publish path and handles your
|
|
48
|
+
registry credentials, that matters. A publishing tool with a dependency tree is a
|
|
49
|
+
supply-chain risk of its own, and this one has no transitive code to audit.
|
|
35
50
|
|
|
36
|
-
|
|
37
|
-
ship:
|
|
51
|
+
Needs Node.js 20+, and `pnpm`, `npm` and `tar` on `PATH`.
|
|
38
52
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
- license
|
|
42
|
-
- package metadata
|
|
43
|
-
- any other files the package intentionally exposes
|
|
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.
|
|
44
55
|
|
|
45
|
-
|
|
46
|
-
workspace-only dependency specs.
|
|
56
|
+
## Package managers
|
|
47
57
|
|
|
48
|
-
|
|
58
|
+
Start `publish-clean` with any package manager and it still packs with `pnpm` and
|
|
59
|
+
publishes with `npm`. So both have to be installed even if your project uses neither. The
|
|
60
|
+
reasons are in [Why it works this way](#why-it-works-this-way).
|
|
49
61
|
|
|
50
|
-
|
|
51
|
-
|
|
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. |
|
|
68
|
+
|
|
69
|
+
The advisory is a warning on stderr, not an error. Nothing behaves differently because of
|
|
70
|
+
it and there's no flag to silence it. Worth seeing once if the rest of your pipeline runs
|
|
71
|
+
on something other than pnpm.
|
|
72
|
+
|
|
73
|
+
For a single package all four behave the same, since nothing in the manifest needs
|
|
74
|
+
resolving before it ships.
|
|
75
|
+
|
|
76
|
+
Monorepos are where it matters. `pnpm pack` resolves `workspace:` and `catalog:` specs by
|
|
77
|
+
finding the dependency inside the packing package's own `node_modules`. What decides
|
|
78
|
+
whether that works is the layout your installer left behind, not which installer it was.
|
|
79
|
+
|
|
80
|
+
Bun gives each package its own `node_modules`, so a Bun workspace packs as it stands: no
|
|
81
|
+
`pnpm-workspace.yaml`, no switching package managers. Yarn hoists workspace dependencies
|
|
82
|
+
to the root instead, so pnpm doesn't find them, and Yarn PnP writes no `node_modules` at
|
|
83
|
+
all. Both need a `pnpm-workspace.yaml` and one `pnpm install` before packing works. A Yarn
|
|
84
|
+
package with no `workspace:` or `catalog:` specs needs neither, because there's nothing to
|
|
85
|
+
resolve.
|
|
86
|
+
|
|
87
|
+
Either way the workspace has to be installed. Pack one nobody has installed and it stops
|
|
88
|
+
on pnpm's own error:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL
|
|
52
92
|
```
|
|
53
93
|
|
|
54
|
-
|
|
94
|
+
Which is what you want. Nothing gets published, and a manifest that would have been
|
|
95
|
+
uninstallable for everyone never reaches the registry. Run your usual install and pack
|
|
96
|
+
again.
|
|
97
|
+
|
|
98
|
+
## Pick your setup
|
|
99
|
+
|
|
100
|
+
### Publishing a public package from CI
|
|
101
|
+
|
|
102
|
+
The common case. `id-token: write` is what lets npm sign the release. Once trusted
|
|
103
|
+
publishing is configured for the package, no npm token is involved at all.
|
|
104
|
+
|
|
105
|
+
```yaml
|
|
106
|
+
# .github/workflows/release.yml
|
|
107
|
+
permissions:
|
|
108
|
+
contents: read
|
|
109
|
+
id-token: write
|
|
110
|
+
steps:
|
|
111
|
+
- uses: actions/checkout@v7
|
|
112
|
+
- uses: pnpm/action-setup@v6
|
|
113
|
+
- uses: actions/setup-node@v7
|
|
114
|
+
with:
|
|
115
|
+
node-version: "24"
|
|
116
|
+
registry-url: https://registry.npmjs.org
|
|
117
|
+
- run: pnpm install --frozen-lockfile
|
|
118
|
+
- run: pnpm run build
|
|
119
|
+
- run: pnpm exec publish-clean -- --access public --tag latest --provenance
|
|
120
|
+
```
|
|
55
121
|
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
- `npm`
|
|
59
|
-
- `tar`
|
|
122
|
+
Always pass the dist-tag. npm defaults to `latest`, which is wrong for a prerelease and
|
|
123
|
+
easy to forget.
|
|
60
124
|
|
|
61
|
-
|
|
62
|
-
|
|
125
|
+
Publishing a package name for the first time cannot use trusted publishing at all. That
|
|
126
|
+
case has its own page: [docs/first-publish.md](docs/first-publish.md).
|
|
63
127
|
|
|
64
|
-
|
|
65
|
-
Package creation intentionally goes through pnpm. The final registry upload
|
|
66
|
-
goes through npm. Yarn and Bun are not treated as equivalent pack/publish
|
|
67
|
-
backends.
|
|
128
|
+
To stop a stray `npm publish` from bypassing all of this:
|
|
68
129
|
|
|
69
|
-
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"scripts": {
|
|
133
|
+
"prepublishOnly": "node -e \"console.error('Publish with publish-clean.'); process.exit(1)\""
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Keeping your existing release tool
|
|
139
|
+
|
|
140
|
+
If Changesets, semantic-release, release-it or np already owns your releases, use
|
|
141
|
+
`publish-clean` as a check rather than replacing the publish:
|
|
70
142
|
|
|
71
143
|
```json
|
|
72
144
|
{
|
|
73
145
|
"scripts": {
|
|
74
|
-
"
|
|
75
|
-
"prepublishOnly": "node -e \"console.error('Use pnpm run publish:clean to publish the cleaned artifact.'); process.exit(1)\"",
|
|
76
|
-
"publish:clean": "bun run check && publish-clean -- --access public --tag latest --provenance"
|
|
77
|
-
},
|
|
78
|
-
"devDependencies": {
|
|
79
|
-
"@anizoptera/publish-clean": "^0.1.0"
|
|
146
|
+
"prepublishOnly": "publish-clean --guard-only"
|
|
80
147
|
}
|
|
81
148
|
}
|
|
82
149
|
```
|
|
83
150
|
|
|
84
|
-
|
|
151
|
+
It packs, cleans and validates, then exits without publishing. A leaked file, an
|
|
152
|
+
unresolved `workspace:` spec or a `main` path that is missing from the tarball fails the
|
|
153
|
+
release before your tool uploads anything. The limit is real though: your tool still
|
|
154
|
+
publishes its own tarball, so you get the checks and not the cleaned manifest.
|
|
155
|
+
|
|
156
|
+
### Looking at what would be published
|
|
85
157
|
|
|
86
158
|
```bash
|
|
87
|
-
pnpm
|
|
159
|
+
pnpm exec publish-clean --dry-run
|
|
88
160
|
```
|
|
89
161
|
|
|
90
|
-
|
|
91
|
-
|
|
162
|
+
Prints the paths of the cleaned package and the exact tarball that would be uploaded, and
|
|
163
|
+
leaves both on disk. Run `tar tzf` on the tarball and read the rewritten `package.json`.
|
|
92
164
|
|
|
93
|
-
|
|
165
|
+
### Publishing a restricted package
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
publish-clean -- --access restricted --tag latest
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
No provenance here, because npm only signs public packages. Do not set `private: true`
|
|
172
|
+
either. npm treats it as a publish block, and `publish-clean` refuses it too.
|
|
173
|
+
|
|
174
|
+
### Publishing one package out of a monorepo
|
|
94
175
|
|
|
95
176
|
```bash
|
|
96
|
-
publish-clean --dry-run
|
|
97
|
-
publish-clean --guard-only
|
|
98
|
-
publish-clean --registry https://registry.npmjs.org -- --access public --tag latest --provenance
|
|
99
177
|
publish-clean packages/my-lib -- --access public --tag next
|
|
100
178
|
```
|
|
101
179
|
|
|
102
|
-
|
|
103
|
-
|
|
180
|
+
## How it works
|
|
181
|
+
|
|
182
|
+
```mermaid
|
|
183
|
+
flowchart TD
|
|
184
|
+
A[Your package directory] -->|pnpm pack| B[Tarball - pnpm decides the file set]
|
|
185
|
+
B --> C[Extract into a temp directory]
|
|
186
|
+
C --> D{No leaked files?}
|
|
187
|
+
D --> E[Clean package.json for consumers]
|
|
188
|
+
E --> F{Every declared main/exports/bin/types path exists?}
|
|
189
|
+
F -->|replace the package.json member| G[Same tarball, cleaned manifest]
|
|
190
|
+
G --> H{Same files, expected manifest, still no leaks?}
|
|
191
|
+
H --> I[npm publish that tarball]
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Any gate that fails exits non-zero and nothing is published. `--dry-run` and
|
|
195
|
+
`--guard-only` run the whole pipeline and stop before the publish.
|
|
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.
|
|
204
|
+
|
|
205
|
+
Workspaces are the reason. A dependency written as `"@acme/utils": "workspace:*"` means
|
|
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.
|
|
209
|
+
|
|
210
|
+
npm never adopted the protocol. It won't even install it:
|
|
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
|
+
```
|
|
255
|
+
|
|
256
|
+
`bun pm pack` exits 0 either way, so nothing tells you until someone tries to install the
|
|
257
|
+
release.
|
|
258
|
+
|
|
259
|
+
One silent way to publish a broken manifest is one too many for the step you can't take
|
|
260
|
+
back.
|
|
261
|
+
|
|
262
|
+
pnpm also applies `publishConfig` field overrides. If your manifest points `main`, `types`
|
|
263
|
+
and `exports` at source for local development and overrides them to `dist` for publishing,
|
|
264
|
+
pnpm swaps them on the way out and drops `publishConfig` itself. npm and Bun both ignore
|
|
265
|
+
those overrides and publish the development paths. That one is a pnpm extension rather
|
|
266
|
+
than a bug in the other two, but the effect on the release is the same.
|
|
267
|
+
|
|
268
|
+
Everything else we compared came out identical: file modes including the executable bit on
|
|
269
|
+
`bin`, negated `files` patterns, dropped symlinks, prerelease versions, pinned
|
|
270
|
+
`workspace:1.2.3` ranges, named catalogs, and refusing a catalog entry that doesn't exist.
|
|
271
|
+
|
|
272
|
+
### Why the manifest is cleaned on a copy
|
|
273
|
+
|
|
274
|
+
The tarball gets extracted into a temp directory and rewritten there. Your working tree
|
|
275
|
+
is never touched.
|
|
276
|
+
|
|
277
|
+
The obvious alternative is what a lot of hand-rolled release scripts do: edit
|
|
278
|
+
`package.json`, publish, edit it back. That's fine until something dies in the middle,
|
|
279
|
+
and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
|
|
280
|
+
twice at once. Cleaning a copy has neither problem and costs a directory in `/tmp`.
|
|
104
281
|
|
|
105
|
-
|
|
282
|
+
### Why the tarball is edited instead of packed again
|
|
283
|
+
|
|
284
|
+
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. Packing first means they exist
|
|
286
|
+
before anything is uploaded: they can be listed, scanned for leaks, kept with
|
|
287
|
+
`--tarball-out` for a build attestation, and then published as themselves. What you
|
|
288
|
+
inspect is what ships.
|
|
289
|
+
|
|
290
|
+
So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
|
|
291
|
+
to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
|
|
292
|
+
cleaning removes it, because it is useless to anyone installing the package. A second pack
|
|
293
|
+
then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
|
|
294
|
+
exclusion, and quietly drops files the first pack included. A package shipping a
|
|
295
|
+
`.gitignore` that excludes any other shipped file loses it.
|
|
296
|
+
|
|
297
|
+
Editing avoids the whole question. Only the `package/package.json` member is replaced;
|
|
298
|
+
every other entry is copied without being decoded, so the file set stays exactly what pnpm
|
|
299
|
+
chose and entry shapes this tool does not model (pax headers for long paths, prefix
|
|
300
|
+
splitting) pass through untouched. It also keeps pnpm's normalised metadata — owner `0:0`,
|
|
301
|
+
a fixed timestamp, mode 644 — which a plain `tar` invocation would replace with the build
|
|
302
|
+
machine's own user and group names.
|
|
303
|
+
|
|
304
|
+
Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
|
|
305
|
+
`prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
|
|
306
|
+
npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
|
|
307
|
+
nothing can alter the artifact after it was checked.
|
|
308
|
+
|
|
309
|
+
### Why npm does the publishing
|
|
310
|
+
|
|
311
|
+
Provenance is an npm feature. The signed attestation behind the "Built and signed on
|
|
312
|
+
GitHub Actions" badge is minted by the npm CLI talking to Sigstore, and trusted
|
|
313
|
+
publishing, which removes the long-lived token entirely, is npm's own OIDC exchange with
|
|
314
|
+
the registry.
|
|
315
|
+
|
|
316
|
+
No other client mints it. `bun publish` offers `--access`, `--tag`, `--otp` and
|
|
317
|
+
`--auth-type`, and nothing at all for provenance or attestation, so publishing through it
|
|
318
|
+
would cost both the badge and the tokenless path. That trade isn't on the table here:
|
|
319
|
+
verifiable provenance is why this package exists.
|
|
320
|
+
|
|
321
|
+
`npm publish` also takes a tarball directly, which is exactly what the previous step
|
|
322
|
+
produced.
|
|
323
|
+
|
|
324
|
+
## What it checks
|
|
325
|
+
|
|
326
|
+
`publish-clean` refuses to continue when:
|
|
327
|
+
|
|
328
|
+
- the package is `private: true`
|
|
329
|
+
- the source package has uncommitted changes, unless disabled
|
|
330
|
+
- the package has no non-empty `files` array, unless disabled
|
|
331
|
+
- the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
|
|
332
|
+
`node_modules`, or private-key files
|
|
333
|
+
- dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
|
|
334
|
+
- declared export, type, import, browser, bin, or side-effect paths are missing
|
|
335
|
+
from the cleaned package
|
|
336
|
+
- the final npm tarball drops files that were present in the cleaned package
|
|
337
|
+
- trusted GitHub publication uses `--provenance` but package repository metadata
|
|
338
|
+
does not match the workflow repository
|
|
339
|
+
|
|
340
|
+
It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm.
|
|
341
|
+
The packing still goes through pnpm, but the warning is there because the rest of your
|
|
342
|
+
release probably should too.
|
|
343
|
+
|
|
344
|
+
Leak checks cannot be turned off by any flag or config key.
|
|
345
|
+
|
|
346
|
+
## What the cleaned manifest keeps
|
|
347
|
+
|
|
348
|
+
Everything a consumer or a registry reads survives: `name`, `version`, `license`,
|
|
349
|
+
`dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
|
|
350
|
+
`bin`, `files`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of
|
|
351
|
+
the public surface.
|
|
352
|
+
|
|
353
|
+
What goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
|
|
354
|
+
`resolutions`, and the config blocks belonging to test runners, linters, formatters,
|
|
355
|
+
coverage tools, build systems and release tools. Scripts go too, apart from the install
|
|
356
|
+
lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
|
|
357
|
+
`prepare` and `uninstall`.
|
|
358
|
+
|
|
359
|
+
Anything the tool does not recognise ships, and you get told it did:
|
|
106
360
|
|
|
107
|
-
```text
|
|
108
|
-
source package
|
|
109
|
-
-> pnpm pack
|
|
110
|
-
-> inspect tarball contents
|
|
111
|
-
-> write cleaned package.json
|
|
112
|
-
-> validate declared package paths
|
|
113
|
-
-> npm pack the cleaned package
|
|
114
|
-
-> validate the final npm tarball
|
|
115
|
-
-> npm publish the final tarball
|
|
116
361
|
```
|
|
362
|
+
publish-clean: these manifest fields are not recognised and were published as-is:
|
|
363
|
+
someToolConfig
|
|
364
|
+
Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
365
|
+
"publish-clean": { "devFields": ["someToolConfig"] }
|
|
366
|
+
"publish-clean": { "keepFields": ["someToolConfig"] }
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
The strip list cannot know about a tool invented after it was written, so new
|
|
370
|
+
`package.json` keys would otherwise leak into every install unnoticed. Dropping them
|
|
371
|
+
instead would be worse: a key some consumer actually resolves would vanish, and you would
|
|
372
|
+
hear about it from a stranger's broken build rather than from your own release.
|
|
117
373
|
|
|
118
|
-
|
|
374
|
+
Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
|
|
375
|
+
would ship instead of trusting this list.
|
|
119
376
|
|
|
120
377
|
## Options
|
|
121
378
|
|
|
@@ -131,6 +388,9 @@ publish-clean [options] [package-dir] [-- npm-publish-args]
|
|
|
131
388
|
- `--skip-file-check`: skip suspicious-file checks and the required `files`
|
|
132
389
|
array check. Critical leak checks still run.
|
|
133
390
|
- `--no-git-checks`: skip the source git cleanliness check.
|
|
391
|
+
- `--tarball-out DIR`: copy the final tarball into `DIR` before publishing. The bytes
|
|
392
|
+
kept are the ones that were published, so a release pipeline can attach them to a
|
|
393
|
+
GitHub Release or sign them with build-provenance attestation.
|
|
134
394
|
- `-h`, `--help`: print usage.
|
|
135
395
|
|
|
136
396
|
Arguments after `--` go to `npm publish`, which publishes the final cleaned
|
|
@@ -149,122 +409,106 @@ Stable project defaults can live in `package.json`:
|
|
|
149
409
|
"registry": "https://registry.npmjs.org",
|
|
150
410
|
"skipFileCheck": false,
|
|
151
411
|
"noGitChecks": false,
|
|
152
|
-
"devFields": ["customBuildOnlyField"]
|
|
412
|
+
"devFields": ["customBuildOnlyField"],
|
|
413
|
+
"keepFields": ["contributes"]
|
|
153
414
|
}
|
|
154
415
|
}
|
|
155
416
|
```
|
|
156
417
|
|
|
157
|
-
|
|
418
|
+
`registry` is written as `publishConfig.registry` on the cleaned manifest and passed to
|
|
419
|
+
`npm publish`, so the package cannot end up on whatever registry the machine happens to
|
|
420
|
+
be pointed at.
|
|
158
421
|
|
|
159
|
-
|
|
422
|
+
`skipFileCheck` drops the suspicious-file check and the requirement for a `files` array.
|
|
423
|
+
Leak checks keep running; those cannot be turned off.
|
|
160
424
|
|
|
161
|
-
`
|
|
425
|
+
`noGitChecks` allows publishing from a dirty working tree. You need it when you publish
|
|
426
|
+
from a build directory or a checkout that is not a git repository.
|
|
162
427
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
- the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
|
|
167
|
-
`node_modules`, or private-key files
|
|
168
|
-
- dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
|
|
169
|
-
- declared export, type, import, browser, bin, or side-effect paths are missing
|
|
170
|
-
from the cleaned package
|
|
171
|
-
- the final npm tarball drops files that were present in the cleaned package
|
|
172
|
-
- trusted GitHub publication uses `--provenance` but package repository metadata
|
|
173
|
-
does not match the workflow repository
|
|
174
|
-
|
|
175
|
-
It also warns when a package-manager lifecycle looks like npm, Yarn, or Bun.
|
|
176
|
-
That warning is intentional: this tool relies on pnpm's pack and publish
|
|
177
|
-
behavior.
|
|
178
|
-
|
|
179
|
-
Critical leak checks cannot be disabled.
|
|
428
|
+
`devFields` lists extra manifest fields to strip, for tooling this package has not heard
|
|
429
|
+
of. Fields that npm or your consumers actually use, like `exports`, `bin`, `engines` and
|
|
430
|
+
the dependency maps, are rejected here, so a typo cannot quietly break your package.
|
|
180
431
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
432
|
+
`keepFields` is the other answer to the same report: the field belongs in the published
|
|
433
|
+
package, stop mentioning it. A VS Code extension needs `contributes` and `publisher` in
|
|
434
|
+
the artifact to work, and no generic publishing tool is ever going to know that.
|
|
184
435
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
From the extracted package manifest, `publish-clean` removes maintainer-only
|
|
188
|
-
fields such as:
|
|
189
|
-
|
|
190
|
-
- `devDependencies`
|
|
191
|
-
- `workspaces`
|
|
192
|
-
- `pnpm`
|
|
193
|
-
- test, lint, format, coverage, build-system, and release-tool config fields
|
|
194
|
-
- scripts except consumer install lifecycle scripts
|
|
195
|
-
|
|
196
|
-
The repository files are not changed.
|
|
436
|
+
Command-line flags override this block. Keep per-release choices such as dist-tags on the
|
|
437
|
+
command line.
|
|
197
438
|
|
|
198
439
|
## What it does not do
|
|
199
440
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
Use tools like Changesets, release-please, semantic-release, release-it, or np
|
|
205
|
-
for that. Use `publish-clean` as the guard or final publish command.
|
|
441
|
+
It isn't a release manager. It won't pick your version number, write a changelog, tag
|
|
442
|
+
anything, push a commit, create a GitHub release, or set up trusted publishing for you.
|
|
443
|
+
It also doesn't check that your entry points resolve correctly for consumers, which is
|
|
444
|
+
what `publint` and `@arethetypeswrong/cli` are for.
|
|
206
445
|
|
|
207
|
-
|
|
208
|
-
`@arethetypeswrong/cli` for package compatibility checks.
|
|
446
|
+
Pick a release manager and a validator to go with it. The next section covers which.
|
|
209
447
|
|
|
210
|
-
|
|
448
|
+
It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
|
|
449
|
+
than copying them, so it has nothing to bundle and refuses:
|
|
211
450
|
|
|
212
|
-
For public npm packages, use npm trusted publishing in GitHub Actions and pass:
|
|
213
|
-
|
|
214
|
-
```bash
|
|
215
|
-
publish-clean -- --access public --tag latest --provenance
|
|
216
451
|
```
|
|
217
|
-
|
|
218
|
-
For restricted npm packages, use the same clean artifact pipeline and usually
|
|
219
|
-
pass:
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
publish-clean -- --access restricted --tag latest
|
|
452
|
+
Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
|
|
223
453
|
```
|
|
224
454
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
[`clean-publish`](https://github.com/shashkovdanil/clean-publish)
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
455
|
+
Doing what it says makes the package publishable again. This is the one thing you give up
|
|
456
|
+
by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
|
|
457
|
+
is loud and tells you the fix. npm and Bun bundle correctly for a standalone package, and
|
|
458
|
+
neither bundles anything for a package inside a workspace, because the dependency hoists
|
|
459
|
+
to the workspace root where the package can't see it.
|
|
460
|
+
|
|
461
|
+
## How it compares
|
|
462
|
+
|
|
463
|
+
[`clean-publish`](https://github.com/shashkovdanil/clean-publish) is the closest prior
|
|
464
|
+
art, and the reason this package exists at all. It copies your source tree into a temp
|
|
465
|
+
directory, deletes the files and fields it recognises, and publishes that.
|
|
466
|
+
|
|
467
|
+
The difference is where the file list comes from. clean-publish starts with your whole
|
|
468
|
+
source tree and subtracts, so anything its rules do not recognise gets published.
|
|
469
|
+
`publish-clean` starts from what `pnpm pack` produced, which is already the exact file
|
|
470
|
+
list your package manager would have shipped, including `files`, `.npmignore`, packlist
|
|
471
|
+
rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
|
|
472
|
+
result is validated again before upload. clean-publish does not re-check its output.
|
|
473
|
+
|
|
474
|
+
Release managers ([Changesets](https://github.com/changesets/changesets),
|
|
475
|
+
[release-please](https://github.com/googleapis/release-please),
|
|
476
|
+
[semantic-release](https://github.com/semantic-release/semantic-release),
|
|
477
|
+
[release-it](https://github.com/release-it/release-it),
|
|
478
|
+
[np](https://github.com/sindresorhus/np)) pick versions, write changelogs, tag, and call
|
|
479
|
+
`npm publish`. None of them look inside the tarball. Use one of them together with this,
|
|
480
|
+
via the `--guard-only` setup above.
|
|
481
|
+
|
|
482
|
+
[`publint`](https://publint.dev) and
|
|
483
|
+
[`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
|
|
484
|
+
check that your entry points and type definitions resolve properly for consumers. That is
|
|
485
|
+
a different question from what is in the tarball. Run them as well.
|
|
486
|
+
|
|
487
|
+
`npm publish --dry-run` prints the file list and stops there. It does not clean anything
|
|
488
|
+
and will happily list a `.env` without complaining.
|
|
489
|
+
|
|
490
|
+
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) proves who
|
|
491
|
+
published. This tool decides what gets published. They solve different halves of the same
|
|
492
|
+
worry, and this package is built to use both.
|
|
493
|
+
|
|
494
|
+
[`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new) publishes preview builds
|
|
495
|
+
per commit without touching the registry. Useful next to this, unrelated to cleaning.
|
|
496
|
+
|
|
497
|
+
Underlying behaviour is defined by [`npm-packlist`](https://github.com/npm/npm-packlist),
|
|
239
498
|
[`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack/),
|
|
240
499
|
[`npm publish`](https://docs.npmjs.com/cli/v11/commands/npm-publish/),
|
|
241
|
-
[`pnpm pack`](https://pnpm.io/cli/pack)
|
|
500
|
+
[`pnpm pack`](https://pnpm.io/cli/pack) and pnpm
|
|
242
501
|
[`publishConfig`](https://pnpm.io/package_json#publishconfig).
|
|
243
502
|
|
|
244
|
-
|
|
245
|
-
[`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new). For provenance,
|
|
246
|
-
use [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). Both
|
|
247
|
-
are useful layers. Neither one cleans the package contents.
|
|
248
|
-
|
|
249
|
-
## Development
|
|
503
|
+
## Contributing
|
|
250
504
|
|
|
251
505
|
```bash
|
|
252
506
|
bun install --frozen-lockfile
|
|
253
507
|
bun run check
|
|
254
508
|
```
|
|
255
509
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
actions-up --yes
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
This package has no runtime dependencies.
|
|
263
|
-
|
|
264
|
-
## Alternatives and references
|
|
265
|
-
|
|
266
|
-
- [`clean-publish`](https://github.com/shashkovdanil/clean-publish)
|
|
267
|
-
- [`npm-packlist`](https://github.com/npm/npm-packlist)
|
|
510
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) has the rest. Security problems go through private
|
|
511
|
+
reporting, not public issues: see [SECURITY.md](SECURITY.md).
|
|
268
512
|
|
|
269
513
|
## License
|
|
270
514
|
|