Skip to content

Publishing Guide

This extension is distributed as an npm package. Users install it via their package manager and register it as a pi extension.

Pre-publish checklist

  • pnpm build passes with zero errors
  • pnpm test passes all tests
  • pnpm version set correctly in package.json
  • CHANGELOG.md updated for the version
  • No node_modules/ or dist/ accidentally tracked in git
  • files field in package.json reviewed

Version bumping

This project follows Semantic Versioning:

Change type Version bump Example
Bug fix patch 0.1.1
New tool/command (non-breaking) minor 0.2.0
Breaking change major 1.0.0 
# patch (bug fix)
pnpm version patch

# minor (new feature)
pnpm version minor

# major (breaking change)
pnpm version major

This updates package.json, package-lock.json (if using npm), and creates a git tag.

Publish to npm

# build one more time
pnpm build

# publish (requires npm login)
pnpm publish --access public

For scoped packages (@your-org/pi-vault-mind), the --access public flag is required for first publish.

Dry run

pnpm publish --dry-run

GitHub Release

After publishing:

  1. Push the version tag: git push origin main --tags
  2. Create a release on GitHub from the new tag
  3. Copy the relevant section from CHANGELOG.md into the release notes

Installation by users

After publishing, users install via:

npm install pi-vault-mind
# or
pnpm add pi-vault-mind
# or
yarn add pi-vault-mind

Then register in their project's package.json:

{
  "pi": {
    "extensions": ["./node_modules/pi-vault-mind/dist/index.js"]
  }
}

Or globally in pi config.

What gets published

The files field in package.json controls the npm tarball contents:

"files": [
  "dist",
  "skills",
  "CHANGELOG.md",
  "README.md",
  "LICENSE"
]

These are included at publish time:

  • dist/ — compiled JavaScript output
  • skills/ — Agent Skills standard SKILL.md and references
  • CHANGELOG.md, README.md, LICENSE — package metadata

Do NOT publish:

  • node_modules/
  • test/
  • .git/
  • .pi/
  • Raw index.ts (if compiling to dist/)
  • test/ (tests are compiled to dist/test/)
  • src/ (compiled to dist/src/)

Automated publishing (GitHub Actions)

To publish from CI, add an npm automation token as NPM_TOKEN to repository secrets, then create:

name: Publish
on:
  push:
    tags:
      - 'v*'
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test
      - run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}