NPM Publishing Guide

Purpose: Quick reference for publishing OpenAgents Control to npm

Time to Read: 3 minutes

Core Concept

OpenAgents Control is published as @nextsystems/oac on npm. Users install globally and run oac [profile] to set up their projects.

Key files:

package.json - Package configuration
bin/oac.js - CLI entry point
.npmignore - Exclude dev files
install.sh - Main installer (runs when user executes oac)

Publishing Workflow

1. Prepare Release

# Update version
npm version patch  # 0.7.0 -> 0.7.1
npm version minor  # 0.7.0 -> 0.8.0

# Update VERSION file
node -p "require('./package.json').version" > VERSION

# Update CHANGELOG.md with changes

2. Test Locally

# Create package
npm pack

# Install globally from tarball
npm install -g ./nextsystems-oac-0.7.1.tgz

# Test CLI
oac --version
oac --help

# Uninstall
npm uninstall -g @nextsystems/oac

3. Publish

# Login (one-time)
npm login

# Publish (scoped packages need --access public)
npm publish --access public

4. Verify

# Check it's live
npm view @nextsystems/oac

# Test installation
npm install -g @nextsystems/oac
oac --version

5. Create GitHub Release

git tag v0.7.1
git push --tags
# Create release on GitHub with changelog

User Installation

Once published, users can:

# Global install (recommended)
npm install -g @nextsystems/oac
oac developer

# Or use npx (no install)
npx @nextsystems/oac developer

Common Issues

"You do not have permission to publish"

npm whoami  # Check you're logged in
npm publish --access public  # Scoped packages need public access

"Version already exists"

npm version patch  # Bump version first

"You must verify your email"

npm profile get  # Check email verification status

Package Configuration

What's included (see package.json → files):

.opencode/ - Agents, commands, context, profiles, skills, tools
scripts/ - Installation scripts
bin/ - CLI entry point
registry.json - Component registry
install.sh - Main installer
Docs (README, CHANGELOG, LICENSE)

What's excluded (see .npmignore):

node_modules/
evals/
.tmp/
Dev files

Security

✅ Enable 2FA: npm profile enable-2fa auth-and-writes
✅ Use strong npm password
✅ @nextsystems scope is protected (only you can publish)

References

Package: https://www.npmjs.com/package/@nextsystems/oac
Stats: https://npm-stat.com/charts.html?package=@nextsystems/oac
Codebase: package.json, bin/oac.js, .npmignore

Last Updated: 2026-01-30

npm-publishing.md 2.8 KB 永久連結 文件歷史 原始文件