Files

Lauren ten Hoor 4fed5b4c48 feat: set up npm publishing infrastructure

Configures DevClaw package for publishing to npm registry with automated
GitHub Actions workflow and comprehensive publishing documentation.

Changes:

1. package.json:
   - Added publishConfig with access: public (required for scoped packages)
   - Already has correct name: @openclaw/devclaw
   - Version: 0.1.0 (ready for initial release)
   - Files array properly configured (dist/, roles/, docs/)
   - prepublishOnly script ensures build before publish

2. GitHub Actions Workflow (.github/workflows/npm-publish.yml):
   - Triggers on release publication
   - Manual workflow dispatch option with tag input
   - Uses NPM_ACCESS_TOKEN secret for authentication
   - Includes npm provenance for supply chain security
   - Publishes as public package
   - Provides summary output after publication

3. Publishing Documentation (PUBLISHING.md):
   - Comprehensive guide for all publishing methods
   - Automated publishing via GitHub releases (recommended)
   - Manual workflow trigger instructions
   - Local publishing fallback
   - Dry-run testing procedures
   - Version management guidelines
   - Troubleshooting common issues
   - Post-publishing checklist

Configuration Details:
- Package name: @openclaw/devclaw (scoped)
- npm account: laurentenhoor
- Access: public (free for scoped packages)
- Provenance: enabled for transparency
- Node.js: >=20 required

Ready for Initial Release:
To publish the first version:
1. Verify NPM_ACCESS_TOKEN is set in GitHub secrets
2. Create and push tag: git tag v0.1.0 && git push --tags
3. Create GitHub release from tag
4. Workflow automatically builds and publishes to npm

Addresses issue #130

2026-02-12 00:13:39 +08:00

4.6 KiB

Raw Blame History

Publishing DevClaw to npm

Package Details

Name: @openclaw/devclaw
npm Profile: https://www.npmjs.com/settings/laurentenhoor/packages
Package URL: https://www.npmjs.com/package/@openclaw/devclaw

Prerequisites

NPM Access Token is configured as NPM_ACCESS_TOKEN secret in GitHub repository settings
npm account: laurentenhoor
Node.js 20+ installed locally for testing

Publishing Methods

Method 1: Automated (Recommended)

Publishing happens automatically via GitHub Actions when a release is created:

Create a new release on GitHub:

# Tag format: v{version} (e.g., v0.1.0)
git tag v0.1.0
git push origin v0.1.0

Create GitHub Release:
- Go to: https://github.com/laurentenhoor/devclaw/releases/new
- Choose the tag you just pushed
- Write release notes
- Click "Publish release"
Monitor the workflow:
- GitHub Actions will automatically build and publish to npm
- Check: https://github.com/laurentenhoor/devclaw/actions

Method 2: Manual Workflow Trigger

Trigger the workflow manually from GitHub Actions:

Go to: https://github.com/laurentenhoor/devclaw/actions/workflows/npm-publish.yml
Click "Run workflow"
Enter the tag name (e.g., v0.1.0)
Click "Run workflow"

Method 3: Local Publishing (Not Recommended)

For testing or emergencies only:

Login to npm:

npm login
# Username: laurentenhoor
# Password: <your-password>
# Email: <your-email>

Test the package:

npm install
npm run build
npm pack --dry-run

Publish:

npm publish --provenance --access public

Testing Before Publishing

Dry Run Test

# Install dependencies
npm install

# Build the package
npm run build

# Check what will be included
npm pack --dry-run

# This will show:
# - Package size
# - Files that will be included
# - Tarball contents

Verify Package Contents

# Create a tarball locally
npm pack

# Extract and inspect
tar -xzf openclaw-devclaw-0.1.0.tgz
ls -la package/

Expected Package Contents

The published package should include:

dist/ - Compiled JavaScript files
roles/ - Default role templates
docs/ - Documentation files
package.json - Package metadata
README.md - Package documentation
.npmignore - Publish exclusions

The package should NOT include:

*.ts source files (except .d.ts)
node_modules/
.git/
tsconfig.json
Development files

Version Management

Bumping Version

Before creating a release, update the version in package.json:

# Patch release (0.1.0 -> 0.1.1)
npm version patch

# Minor release (0.1.0 -> 0.2.0)
npm version minor

# Major release (0.1.0 -> 1.0.0)
npm version major

This automatically:

Updates package.json
Creates a git commit
Creates a git tag

Then push:

git push && git push --tags

Verifying Publication

After publishing, verify:

Package appears on npm:
- https://www.npmjs.com/package/@openclaw/devclaw

Test installation:

# In a temporary directory
mkdir test-install && cd test-install
npm install @openclaw/devclaw

Check package contents:
```
ls -la node_modules/@openclaw/devclaw/
```

Troubleshooting

Build Fails

# Clean and rebuild
rm -rf dist/ node_modules/
npm install
npm run build

Publish Fails - Already Published

If the version already exists on npm, you need to bump the version:

npm version patch  # or minor/major
git push && git push --tags

Publish Fails - Authentication

Check that NPM_ACCESS_TOKEN secret is correctly set in GitHub:

Go to: https://github.com/laurentenhoor/devclaw/settings/secrets/actions
Verify NPM_ACCESS_TOKEN exists and is valid

Generate a new token if needed:

https://www.npmjs.com/settings/laurentenhoor/tokens
Token type: "Automation" (for CI/CD)
Copy token and update GitHub secret

Provenance Fails

If --provenance fails:

Ensure id-token: write permission is set in workflow
Check that GitHub Actions is enabled
Verify repository settings allow provenance

Post-Publishing Checklist

Verify package appears on npm
Test installation in a fresh project
Update CHANGELOG.md with release notes
Announce release in project channels
Close related issues/PRs
Update documentation if needed

Support

For issues with publishing:

Check GitHub Actions logs
Review npm publish documentation
Contact package maintainer: laurentenhoor

4.6 KiB Raw Blame History