From 29c710551d3e3ecbcd3f1f9fd70fb00ca7de9eb4 Mon Sep 17 00:00:00 2001 From: dipto0321 Date: Thu, 2 Jul 2026 01:55:09 +0600 Subject: [PATCH] docs(release): document the npm wrapper publish step in the v1.0.0 checklist Fills the gap left after #34 shipped the wrapper source into nodeup-npm/. The wrapper now exists on a clean install-from-tarball path, but publishing it to the npmjs.com registry is a manual step that's distinct from the GitHub release flow: - npmjs.com account + 2FA (authenticator mode) prereq - the v1.0.0 GitHub release has to exist before `npm publish`, because scripts/install.js fetches from the matching tag - the publish flow with OTP prompt and a `npm pack --dry-run` pre-flight to confirm only the 5 expected files ship - a note on automating later via NPM_TOKEN, after the first manual publish has confirmed the account + package name wiring Tracking issue: #35. Co-Authored-By: Sonnet 4.6 --- docs/release-checklist.md | 57 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 96d42d1..83abe5e 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -37,7 +37,62 @@ git push origin vX.Y.Z - [ ] All 6 binaries attached + checksums.txt - [ ] Homebrew formula pushed to `dipto0321/homebrew-tap` - [ ] Scoop manifest pushed to `dipto0321/scoop-bucket` -- [ ] npm wrapper published to registry (Phase 7) +- [ ] npm wrapper published to the npm registry (see below) + +### Publishing `nodeup-npm` to the npm registry + +The npm wrapper lives in `nodeup-npm/` at the repo root and ships via +`npm publish` **after** the GitHub release is up. The wrapper's +`postinstall` script (`scripts/install.js`) fetches the binary +matching the `binaryVersion` field in `package.json`, so the GitHub +release for that version **must already exist** before publishing +the wrapper — otherwise every install 404s on the binary download. + +```bash +# 1. Sanity-check the tarball before publishing. This should print +# exactly 5 files: LICENSE, README.md, package.json, and the two +# scripts. No bin/, no .npmignore, no node_modules. +cd nodeup-npm +npm pack --dry-run +cd .. + +# 2. Log in to npmjs.com (one-time per machine; uses your npm account +# credentials + email/password). After 2FA is enabled on the +# account, `npm login` will ask for a one-time code from your +# authenticator. +npm login + +# 3. From the wrapper directory, publish. npm will prompt for the +# OTP code on publish (not on login) — keep your authenticator +# open. +cd nodeup-npm +npm publish +cd .. +``` + +**Required once, not per release:** + +- An `npmjs.com` account with publish rights on the `nodeup` package + name. The package name must be claimed on npm before the first + publish — `npm publish` will fail with `You do not have permission + to publish "nodeup"` if it isn't. +- **2FA enabled** on the npm account. Publishing to npmjs.com + requires 2FA; configure it under + `https://www.npmjs.com/settings//security`. + Authenticator-app mode (`Authenticator` level) is the minimum — + SMS and email-only modes are not accepted for publish. + +**Repeat for every wrapper version bump.** The flow is the same +when the wrapper pins to a new `binaryVersion`: confirm the GitHub +release exists, `npm pack --dry-run`, then `npm publish`. + +**Can I automate it?** Yes, but not for the very first publish. Add +a repo secret `NPM_TOKEN` (a publish-only automation token from +`https://www.npmjs.com/settings//tokens`) and a +release workflow step that runs `npm publish` from `nodeup-npm/` on +tag push. Until you've done at least one manual publish to confirm +the package name and the account are wired up, keep this step in +the human checklist. ## Post-release