4fed5b4c48
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
218 lines
4.6 KiB
Markdown
218 lines
4.6 KiB
Markdown
# 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
|
|
|
|
1. **NPM Access Token** is configured as `NPM_ACCESS_TOKEN` secret in GitHub repository settings
|
|
2. **npm account:** laurentenhoor
|
|
3. **Node.js 20+** installed locally for testing
|
|
|
|
## Publishing Methods
|
|
|
|
### Method 1: Automated (Recommended)
|
|
|
|
Publishing happens automatically via GitHub Actions when a release is created:
|
|
|
|
1. **Create a new release** on GitHub:
|
|
```bash
|
|
# Tag format: v{version} (e.g., v0.1.0)
|
|
git tag v0.1.0
|
|
git push origin v0.1.0
|
|
```
|
|
|
|
2. **Create GitHub Release:**
|
|
- Go to: https://github.com/laurentenhoor/devclaw/releases/new
|
|
- Choose the tag you just pushed
|
|
- Write release notes
|
|
- Click "Publish release"
|
|
|
|
3. **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:
|
|
|
|
1. Go to: https://github.com/laurentenhoor/devclaw/actions/workflows/npm-publish.yml
|
|
2. Click "Run workflow"
|
|
3. Enter the tag name (e.g., `v0.1.0`)
|
|
4. Click "Run workflow"
|
|
|
|
### Method 3: Local Publishing (Not Recommended)
|
|
|
|
For testing or emergencies only:
|
|
|
|
1. **Login to npm:**
|
|
```bash
|
|
npm login
|
|
# Username: laurentenhoor
|
|
# Password: <your-password>
|
|
# Email: <your-email>
|
|
```
|
|
|
|
2. **Test the package:**
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
npm pack --dry-run
|
|
```
|
|
|
|
3. **Publish:**
|
|
```bash
|
|
npm publish --provenance --access public
|
|
```
|
|
|
|
## Testing Before Publishing
|
|
|
|
### Dry Run Test
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
git push && git push --tags
|
|
```
|
|
|
|
## Verifying Publication
|
|
|
|
After publishing, verify:
|
|
|
|
1. **Package appears on npm:**
|
|
- https://www.npmjs.com/package/@openclaw/devclaw
|
|
|
|
2. **Test installation:**
|
|
```bash
|
|
# In a temporary directory
|
|
mkdir test-install && cd test-install
|
|
npm install @openclaw/devclaw
|
|
```
|
|
|
|
3. **Check package contents:**
|
|
```bash
|
|
ls -la node_modules/@openclaw/devclaw/
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Fails
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|