Merge pull request #131 from laurentenhoor/feat/130-npm-publish
feat: set up npm publishing infrastructure
This commit is contained in:
Lauren ten Hoor
GitHub
49
.github/workflows/npm-publish.yml
vendored
Normal file
49
.github/workflows/npm-publish.yml
vendored
Normal file
@@ -0,0 +1,49 @@
|
||||
name: Publish to npm
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [published]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: 'Tag to publish (e.g., v0.1.0)'
|
||||
required: true
|
||||
type: string
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write # For npm provenance
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ github.event.release.tag_name || inputs.tag }}
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
registry-url: 'https://registry.npmjs.org'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Publish to npm
|
||||
run: npm publish --provenance --access public
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
|
||||
|
||||
- name: Publish summary
|
||||
run: |
|
||||
echo "## ✅ Published to npm" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Package:** \`@openclaw/devclaw\`" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Version:** \`$(node -p "require('./package.json').version")\`" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**URL:** https://www.npmjs.com/package/@openclaw/devclaw" >> $GITHUB_STEP_SUMMARY
|
||||
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
|
||||
@@ -32,6 +32,9 @@
|
||||
"roles/",
|
||||
"docs/"
|
||||
],
|
||||
"publishConfig": {
|
||||
"access": "public"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"check": "tsc --noEmit",
|
||||
|
||||
Reference in New Issue
Block a user