|
| 1 | +<p align="center"> |
| 2 | + <h1 align="center">pnpm-dev-kit</h1> |
| 3 | + <p align="center"> |
| 4 | + <a href="https://www.npmjs.com/package/pnpm-dev-kit"><img src="https://img.shields.io/npm/v/pnpm-dev-kit.svg?style=flat-square" alt="npm version"></a> |
| 5 | + <a href="https://www.npmjs.com/package/pnpm-dev-kit"><img src="https://img.shields.io/npm/dm/pnpm-dev-kit.svg?style=flat-square" alt="npm downloads"></a> |
| 6 | + <a href="https://github.com/license"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license"></a> |
| 7 | + </p> |
| 8 | + <p align="center">PDK - PNPM Dev Kit, An efficient PNPM workspace development and publishing tool.</p> |
| 9 | +</p> |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +- 💻 **Dev Mode**: Quickly launch on-demand development builds for monorepo packages |
| 14 | +- 🚀 **Release Management**: Automated version bumping and publishing |
| 15 | +- 🔧 **Patch System**: Repair failed package publications |
| 16 | +- 📝 **Changelog Generation**: Automatic, customizable changelog creation |
| 17 | +- 🏷️ **GitHub Release**: Automatic GitHub release creation with changelog extraction |
| 18 | + |
| 19 | +## Install |
| 20 | + |
| 21 | +```bash |
| 22 | +# Using npm |
| 23 | +npm install --save-dev pnpm-dev-kit |
| 24 | + |
| 25 | +# Using yarn |
| 26 | +yarn add --dev pnpm-dev-kit |
| 27 | + |
| 28 | +# Using pnpm |
| 29 | +pnpm add -D pnpm-dev-kit |
| 30 | +``` |
| 31 | + |
| 32 | +For global installation: |
| 33 | + |
| 34 | +```bash |
| 35 | +npm install -g pnpm-dev-kit |
| 36 | +``` |
| 37 | + |
| 38 | +## Usage |
| 39 | + |
| 40 | +### Development Mode |
| 41 | + |
| 42 | +Quickly start development mode to build packages on demand when files change: |
| 43 | + |
| 44 | +```bash |
| 45 | +# Using the CLI |
| 46 | +pdk dev |
| 47 | + |
| 48 | +# Or with npm script |
| 49 | +npm run dev |
| 50 | +``` |
| 51 | + |
| 52 | +**Interactive Features:** |
| 53 | + |
| 54 | +- Type `n` to select a package to build manually |
| 55 | +- Type `ps` to list running processes |
| 56 | +- Type package name to build a specific package |
| 57 | + |
| 58 | +### Release Process |
| 59 | + |
| 60 | +**Standard Release:** |
| 61 | +```bash |
| 62 | +# Complete release (recommended) |
| 63 | +pdk release --push-tag --create-github-release |
| 64 | + |
| 65 | +# Canary release for CI/CD |
| 66 | +pdk release --canary |
| 67 | +``` |
| 68 | + |
| 69 | +**Release Flow:** |
| 70 | +1. Select version type (patch/minor/major/prerelease) |
| 71 | +2. Choose NPM tag (latest/next/beta) |
| 72 | +3. Update workspace dependencies |
| 73 | +4. Publish packages to NPM |
| 74 | +5. Create git tag and push to remote |
| 75 | +6. Generate CHANGELOG.md |
| 76 | +7. Create GitHub Release |
| 77 | + |
| 78 | +**Failed Release Recovery:** |
| 79 | +```bash |
| 80 | +pdk patch --version 1.0.0 --tag latest |
| 81 | +``` |
| 82 | + |
| 83 | +**Changelog Generation:** |
| 84 | +```bash |
| 85 | +# Standard changelog |
| 86 | +pdk changelog --version 1.0.0 --beautify --commit --git-push |
| 87 | + |
| 88 | +# AI-powered changelog |
| 89 | +pdk changelog --version 1.0.0 --use-ai --provider openai --model gpt-4o |
| 90 | +``` |
| 91 | + |
| 92 | +**GitHub Release:** |
| 93 | +```bash |
| 94 | +pdk github-release --version 1.0.0 |
| 95 | +pdk github-release --dry-run # Preview |
| 96 | +``` |
| 97 | + |
| 98 | +**Key Options:** |
| 99 | +- `--dry-run`: Preview without changes |
| 100 | +- `--run-in-band`: Publish packages in series |
| 101 | +- `--build`: Custom build script before release |
| 102 | +- `--ignore-scripts`: Skip npm scripts |
| 103 | +- `--auto-create-release-branch`: Auto-create release branch |
| 104 | +- `--filter-scopes`: Filter by scope (default: tars,agent,tarko,o-agent,tars-stack,browser,infra,mcp,all) |
| 105 | +- `--filter-types`: Filter by commit type (default: feat,fix) |
| 106 | + |
| 107 | +## Configuration |
| 108 | + |
| 109 | +**package.json Scripts:** |
| 110 | +```json |
| 111 | +{ |
| 112 | + "scripts": { |
| 113 | + "dev": "pdk dev", |
| 114 | + "release": "pdk release --push-tag", |
| 115 | + "release:full": "pdk release --push-tag --create-github-release", |
| 116 | + "release:canary": "pdk release --canary", |
| 117 | + "github-release": "pdk github-release", |
| 118 | + "changelog": "pdk changelog", |
| 119 | + "patch": "pdk patch --version $(node -p \"require('./package.json').version\") --tag latest" |
| 120 | + } |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +**Workspace Setup:** |
| 125 | +- Uses `pnpm-workspace.yaml` for package discovery |
| 126 | +- Follows conventional commit standards |
| 127 | +- Auto-updates internal workspace dependencies |
| 128 | + |
| 129 | +**CI/CD Integration:** |
| 130 | +```yaml |
| 131 | +# .github/workflows/release.yml |
| 132 | +name: Release |
| 133 | +on: |
| 134 | + push: |
| 135 | + tags: |
| 136 | + - 'v*' |
| 137 | +jobs: |
| 138 | + release: |
| 139 | + runs-on: ubuntu-latest |
| 140 | + steps: |
| 141 | + - uses: actions/checkout@v3 |
| 142 | + - uses: actions/setup-node@v3 |
| 143 | + with: |
| 144 | + node-version: '18' |
| 145 | + - run: npm install -g pnpm |
| 146 | + - run: pnpm install |
| 147 | + - run: pnpm run release:full |
| 148 | + env: |
| 149 | + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 150 | + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} |
| 151 | +``` |
| 152 | +
|
| 153 | +**Best Practices:** |
| 154 | +- Always release from latest main branch |
| 155 | +- Ensure clean working directory |
| 156 | +- Run tests before release |
| 157 | +- Use `--dry-run` for testing |
| 158 | +- Canary format: `{version}-canary-{commitHash}-{timestamp}` |
| 159 | +- Auto-rollback on publish failure |
| 160 | + |
| 161 | +## License |
| 162 | + |
| 163 | +This project is licensed under the Apache License 2.0. |
0 commit comments