laurigates/bun-publishing

Bun npm Publishing

When to Use This Skill

| Scenario | Use this skill | Alternative | |----------|---------------|-------------| | Configuring package.json for npm publishing | Yes | N/A | | Publishing a package to npm registry | Yes | N/A | | Setting up CLI tool packaging with bin | Yes | N/A | | Configuring provenance signing | Yes | N/A | | Setting up release-please automation | Yes | N/A | | Validating tarball contents before publish | Yes | N/A | | Installing or updating dependencies | No - use bun-package-manager | bun-add for quick additions | | Building/bundling before publish | No - use bun-development | bun-build for quick builds |

Core Expertise

Publishing npm packages built with Bun:

• Package.json configuration for npm registry
• CLI tool packaging with executable binaries
• Provenance signing for supply chain security
• Release automation with release-please

Package.json Configuration

Essential Publishing Fields

{
  "name": "@org/package-name",
  "version": "1.0.0",
  "description": "Package description",
  "main": "build/index.js",
  "type": "module",
  "publishConfig": {
    "access": "public"
  },
  "files": [
    "build/",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "tsc && chmod +x build/index.js",
    "prepublishOnly": "bun run build"
  },
  "engines": {
    "node": ">=20.0.0",
    "bun": ">=1.0.0"
  }
}

Field Reference

| Field | Purpose | |-------|---------| | publishConfig.access | public required for scoped packages | | files | Whitelist of files/dirs to include in tarball | | main | Entry point for CommonJS/ES import | | type | module for ESM, commonjs for CJS | | engines | Runtime version requirements | | prepublishOnly | Runs before npm publish |

Scoped Packages

Scoped packages (@org/name) require explicit public access:

{
  "name": "@myorg/mypackage",
  "publishConfig": {
    "access": "public"
  }
}

Or use the CLI flag:

npm publish --access public

CLI Tool Packaging

Binary Entry Configuration

{
  "bin": {
    "mycli": "build/index.js"
  }
}

For single-command packages:

{
  "bin": "build/index.js"
}

Executable Setup

Entry point requires shebang and executable permission:

#!/usr/bin/env node
// build/index.js

import { main } from "./main.js";
main();

Build script must set permissions:

{
  "scripts": {
    "build": "tsc && chmod +x build/index.js"
  }
}

Makefile Integration

build-prod:
	rm -rf build
	tsc --declaration --sourceMap
	chmod +x build/index.js

publish: build-prod
	npm publish --access public

Publishing Commands

Manual Publishing

# Standard publish (runs prepublishOnly)
npm publish

# Scoped package (requires --access public)
npm publish --access public

# Dry run to verify contents
npm publish --dry-run

# View what would be published
npm pack --dry-run

With Provenance

Supply chain security via npm provenance:

npm publish --provenance --access public

Requires:

• CI environment (GitHub Actions, GitLab CI)
• id-token: write permission in workflow
• npm registry-url configured

Files Whitelist

Recommended Pattern

{
  "files": [
    "build/",
    "README.md",
    "LICENSE"
  ]
}

What to Include

| Include | Examples | |---------|----------| | Build output | build/, dist/ | | Type definitions | *.d.ts (usually in build) | | Documentation | README.md, LICENSE | | Config scripts | User-facing setup scripts |

What to Exclude

Already excluded by npm (no need to list):

• node_modules/
• .git/
• .env*
• *.log

Explicitly exclude via .npmignore if needed:

src/
tests/
*.test.ts
.github/

Release Automation

Release-Please Integration

.github/workflows/release-please.yml:

name: Release Please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
    steps:
      - uses: google-github-actions/release-please-action@v4
        id: release
        with:
          release-type: node
          package-name: mypackage

  publish:
    needs: release-please
    if: ${{ needs.release-please.outputs.release_created == 'true' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Conventional Commits for Versioning

| Commit Type | Version Bump | |-------------|--------------| | feat: | Minor (1.x.0) | | fix: | Patch (1.0.x) | | feat!: or BREAKING CHANGE: | Major (x.0.0) | | chore:, docs:, refactor: | No bump |

Pre-publish Validation

Build Hook

{
  "scripts": {
    "prepublishOnly": "bun run build"
  }
}

Full Validation

# Type check
bun run tsc --noEmit

# Lint
bun run check

# Test
bun test

# Build
bun run build

# Verify tarball contents
npm pack --dry-run

Repository Metadata

Complete metadata for npm and GitHub:

{
  "repository": {
    "type": "git",
    "url": "https://github.com/org/repo.git"
  },
  "homepage": "https://github.com/org/repo#readme",
  "bugs": {
    "url": "https://github.com/org/repo/issues"
  },
  "keywords": ["keyword1", "keyword2"],
  "author": "Name <email>",
  "license": "MIT"
}

Agentic Optimizations

| Context | Command | |---------|---------| | Preview tarball | npm pack --dry-run | | Preview publish | npm publish --dry-run | | Scoped publish | npm publish --access public | | Provenance | npm publish --provenance --access public | | Check outdated | npm outdated | | View package | npm view @org/pkg |

Quick Reference

Publishing Flags

| Flag | Description | |------|-------------| | --access public | Required for scoped packages | | --provenance | Enable supply chain provenance | | --dry-run | Preview without publishing | | --tag <tag> | Publish with dist-tag (e.g., beta) |

Package.json Scripts

| Script | When It Runs | |--------|--------------| | prepublish | Before pack and publish (deprecated) | | prepublishOnly | Before publish only | | prepack | Before pack and publish | | postpack | After pack | | postpublish | After publish |

CI Environment Variables

| Variable | Purpose | |----------|---------| | NODE_AUTH_TOKEN | npm authentication | | NPM_TOKEN | Alternative npm token name |

Common Issues

Scoped package 402 error:

# Add --access public for scoped packages
npm publish --access public

Missing files in tarball:

# Check what's included
npm pack --dry-run

# Verify files array in package.json

Binary not executable after install:

# Ensure shebang in entry point
#!/usr/bin/env node

# Ensure chmod in build script
chmod +x build/index.js

2FA publish (EOTP) is not automatable:

A non-interactive shell — a CI step, or an agent's Bash tool — cannot supply a one-time password. npm publish fails with:

npm error code EOTP
npm error This operation requires a one-time password.

Two ways through:

• Human, interactive: npm publish --otp=<6-digit-code> (the code comes from the publisher's authenticator app, not from npm on demand).
• Automation token (CI / unattended): a Granular/Automation token (npmjs.com → Access Tokens) bypasses 2FA at publish time. Put it in NODE_AUTH_TOKEN / NPM_TOKEN. This is exactly why the release-please workflow above publishes cleanly while a local npm publish prompts — CI uses the token, the human uses the OTP.

An agent that hits EOTP should hand the publish to the user or switch the repo to an automation token — it cannot mint or supply one itself (npm token create also requires a valid, OTP-satisfied session).

Fresh publish 404s for a few minutes (propagation lag):

Right after a first publish, public / unauthenticated reads can 404 while the package is genuinely live — the access record updates instantly but the public metadata CDN lags. Don't conclude the publish failed. Confirm with authenticated, version-pinned checks:

npm access list packages              # shows it under your account immediately
npm view @org/pkg@<version> _id       # version-pinned, authed — resolves once live
npm pack @org/pkg@<version>           # actually fetches the tarball (definitive)

Signature of propagation lag (not a private/failed publish): a public 404 plus npm access list packages shows the package plus an authed npm pack @org/pkg@<version> succeeds. (npm config get //registry.npmjs.org/:_authToken often returns empty even when logged in, so a hand-rolled curl with that "token" is an unauthenticated probe — use the npm CLI itself, which reads auth correctly, to test.)