| name | npm-publish |
| description | Publish packages to npm registry. Use this skill when asked to publish, release, or deploy a package to npm. Handles granular access token creation, authentication, and publishing with 2FA bypass. |
npm Publish Skill
Complete workflow for publishing packages to the npm registry, including granular access token creation via the npmjs.com web UI.
Prerequisites
- npm account with package write access
- Playwright browser tool available for token creation
- Package must be built (
npm run build) and tests passing (npm test)
Publishing Workflow
Step 1: Check if already published
npm view <package-name> version
If the package/version already exists, bump the version in package.json before proceeding.
Step 2: Build and test
npm run build && npm test
Ensure there are no build errors and all tests pass before publishing.
Step 3: Create granular access token (if needed)
If you don't have a valid token:
- Navigate to
https://www.npmjs.com/settings/~/tokens using Playwright browser
- If not logged in, the user must authenticate (npm sends email OTP)
- Click "Generate New Token"
- Fill in:
- Token name:
<package-name>-publish
- Bypass 2FA: Check the checkbox
- Packages and scopes → Permissions: "Read and write"
- Select packages: "All packages" radio button
- Expiration: 90 days (maximum for write tokens)
- Click "Generate token"
- Copy the token from the success page (starts with
npm_)
Step 4: Configure and publish
npm config set //registry.npmjs.org/:_authToken=<TOKEN>
npm publish --access public
Step 5: Verify publication
npm view <package-name> version
Confirm the published version matches what you expected.
Step 6: Clean up token from local config
npm config delete //registry.npmjs.org/:_authToken
This removes the token from your local .npmrc so it is not accidentally leaked.
Important Notes
- npm granular tokens with write access have a max 90-day expiry
- Bypass 2FA checkbox MUST be enabled for CLI publishing to work
- The "All packages" radio must be explicitly selected (it's not selected by default despite appearing so)
- Always clean up tokens from local
.npmrc after publishing
- Token stays saved in npmjs.com account for re-use within its expiry window
Troubleshooting
| Problem | Cause | Fix |
|---|
| E403 error | Token doesn't have bypass 2FA enabled, or expired | Regenerate token with bypass 2FA checked |
| "Must select at least one package" | "All packages" radio not actually selected | Click "All packages" radio button explicitly |
| Email OTP required | npm login requires email verification | User must check their email — cannot be automated |
| E404 on npm view | Package not yet published | This is expected for first-time publishes |
| Version conflict | Version already exists on registry | Bump version in package.json before publishing |
