Publishing duroxide-node to npm

Pre-Publish Checklist

Before publishing, verify ALL of the following:

1. Clean Build

bash
1cd duroxide-node
2
3# Clippy — must pass with zero warnings
4cargo clippy --all-targets
5
6# Release build via napi
7npx napi build --platform --release

2. Tests Pass

bash
1# All 52 tests must pass (requires DATABASE_URL in .env)
2npm run test:all

3. Changelog Updated

• CHANGELOG.md must have an entry for the new version
• Follow Keep a Changelog format
• Include all Added/Changed/Fixed/Removed sections as applicable

4. README Points to Changelog

Verify README.md contains a link to CHANGELOG.md:

markdown
1> See [CHANGELOG.md](CHANGELOG.md) for release notes.

5. Version Bumped

Update version in package.json and all platform package.json files:

bash
1# Bump version (also updates npm/npm/*/package.json)
2npx napi version

Or manually update package.json version field and ensure optionalDependencies versions match.

Build Platform Binaries

Three platforms are supported:

darwin-arm64 (macOS Apple Silicon) — native build

bash
1npx napi build --platform --release
2cp duroxide.darwin-arm64.node npm/npm/darwin-arm64/

darwin-x64 (macOS Intel) — native cross-compile

bash
1rustup target add x86_64-apple-darwin  # one-time
2npx napi build --platform --release --target x86_64-apple-darwin
3cp duroxide.darwin-x64.node npm/npm/darwin-x64/

linux-x64-gnu — Docker build

bash
1docker run --rm -v "$(pwd):/build" -w /build --platform linux/amd64 rust:latest bash -c "
2  curl -fsSL https://deb.nodesource.com/setup_22.x | bash - &&
3  apt-get install -y nodejs &&
4  npm install &&
5  npx napi build --platform --release --target x86_64-unknown-linux-gnu
6"
7cp duroxide.linux-x64-gnu.node npm/npm/linux-x64-gnu/

win32-x64-msvc (Windows) — Docker + cargo-xwin (optional)

Not currently built. Can be added with cargo-xwin in a Linux Docker container.

Publish Order

Platform packages MUST be published before the main package (npm resolves optionalDependencies at install time).

1. Publish platform packages

bash
1# Requires an npm Automation token (bypasses 2FA)
2AUTH="--//registry.npmjs.org/:_authToken=<TOKEN>"
3
4cd npm/npm/darwin-arm64 && npm publish --access public $AUTH && cd -
5cd npm/npm/darwin-x64   && npm publish --access public $AUTH && cd -
6cd npm/npm/linux-x64-gnu && npm publish --access public $AUTH && cd -

2. Publish main package

bash
1cd duroxide-node
2npm publish --access public $AUTH

The prepublishOnly script runs napi prepublish -t npm automatically, which verifies platform binaries exist.

3. Verify (MANDATORY — DO NOT SKIP)

⚠️ A release is NOT complete until ALL packages are verified on npm. The main duroxide package depends on platform binary packages via optionalDependencies. If any platform package is missing, the install will silently succeed but the native binary won't load at runtime.

Step 3a: Verify all platform packages exist on npm

bash
1VERSION="<NEW_VERSION>"  # e.g., 0.1.14
2for pkg in duroxide-darwin-arm64 duroxide-darwin-x64 duroxide-linux-x64-gnu duroxide-windows-x64; do
3  echo -n "$pkg@$VERSION: "
4  npm view "$pkg@$VERSION" version 2>/dev/null && echo "✅" || echo "❌ MISSING — DO NOT PROCEED"
5done

If ANY platform package shows ❌, STOP and fix before continuing. The most common failure mode is version skew — the platform package.json files (npm/npm/*/package.json) were not bumped to match the main package.json version. This causes npm publish to try re-publishing an old version, which npm rejects with E403, and the || true in CI silently swallows the error.

Step 3b: Verify main package

bash
1npm view "duroxide@$VERSION" version

Step 3c: Integration test in a clean directory

bash
1cd /tmp && mkdir test-duroxide && cd test-duroxide
2npm install duroxide@$VERSION
3node -e "const d = require('duroxide'); console.log('loaded:', Object.keys(d).slice(0,5))"
4rm -rf /tmp/test-duroxide

All three steps must pass. If Step 3c fails with a missing native binary error, one of the platform packages is broken.

npm Authentication

• Publishing requires an Automation token (bypasses 2FA)
• Create at: https://www.npmjs.com/settings/<username>/tokens
• Token type: Automation (not Granular, unless "bypass 2FA" is enabled)
• Never commit tokens to source code

Version Cascade

When bumping versions, update optionalDependencies in the main package.json to match:

json
1"optionalDependencies": {
2  "duroxide-darwin-arm64": "<NEW_VERSION>",
3  "duroxide-darwin-x64": "<NEW_VERSION>",
4  "duroxide-linux-x64-gnu": "<NEW_VERSION>",
5  "duroxide-win32-x64-msvc": "<NEW_VERSION>"
6}

Summary Checklist

• cargo clippy --all-targets — zero warnings
• npx napi build --platform --release — clean build
• npm run test:all — all tests pass
• CHANGELOG.md — updated for new version
• README.md — links to CHANGELOG.md
• Version bumped in package.json + ALL platform packages (npm/npm/*/package.json)
• Platform binaries built and copied to npm/npm/*/
• Platform packages published first
• Main package published
• ALL 4 platform packages verified on npm (npm view <pkg>@<version>)
• Main package verified on npm (npm view duroxide@<version>)
• Verified with npm install duroxide in a clean directory — native binary loads