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

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

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 + platform packages
• Platform binaries built and copied to npm/npm/*/
• Platform packages published first
• Main package published
• Verified with npm install duroxide in a clean directory