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
This commit is contained in:
Lauren ten Hoor
217
PUBLISHING.md
Normal file
217
PUBLISHING.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user