Skip to content

PUBLISHING.md

Latest commit

 

History

History
156 lines (108 loc) · 3.48 KB

PUBLISHING.md

File metadata and controls

156 lines (108 loc) · 3.48 KB

Publishing Guide

This document explains how to publish the @sf-explorer/agentscript-migration-tool package to npm.

Prerequisites

  1. npm account: Create an account at https://www.npmjs.com/
  2. Login: Run npm login in your terminal
  3. Organization: If publishing under @sf-explorer scope, ensure you have access to that organization

Pre-Publishing Checklist

  • Update version in package.json (follow semantic versioning)
  • Run npm run build to ensure TypeScript compiles successfully
  • Run npm test to ensure all tests pass
  • Review README.md for accuracy
  • Verify .npmignore excludes source files (only dist/ should be published)
  • Check that package.json has correct main, types, and files fields

Build and Test

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Check coverage
npm run test:coverage

Publishing Steps

1. Update Version

Update the version in package.json following semantic versioning:

  • Patch (1.0.0 → 1.0.1): Bug fixes
  • Minor (1.0.0 → 1.1.0): New features, backward compatible
  • Major (1.0.0 → 2.0.0): Breaking changes

2. Build

npm run build

3. Test Locally (Optional)

Test the package locally before publishing:

# In this package directory
npm pack

# In another project
npm install /path/to/agentscript-migration-tool-1.0.0.tgz

4. Publish to npm

# Dry run (see what would be published)
npm publish --dry-run

# Publish to npm
npm publish --access public

Note: The --access public flag is required when publishing scoped packages (@sf-explorer/...) for the first time.

5. Verify Publication

  1. Visit https://www.npmjs.com/package/@sf-explorer/agentscript-migration-tool
  2. Verify the package appears correctly
  3. Test installation: npm install @sf-explorer/agentscript-migration-tool

Post-Publishing

  • Create a GitHub release (if using GitHub)
  • Update documentation if needed
  • Announce the release (blog post, community forums, etc.)

Updating the Package

For subsequent releases:

  1. Make your changes
  2. Update version in package.json
  3. Update CHANGELOG.md (if you create one)
  4. Run npm run build
  5. Run npm test
  6. Run npm publish

Troubleshooting

"You do not have permission to publish"

  • Ensure you're logged in: npm whoami
  • Check organization access if using scoped package
  • Verify package name doesn't conflict with existing packages

"Package name already exists"

  • Choose a different name or scope
  • Or contact the maintainer of the existing package

Build Errors

  • Ensure TypeScript compiles: npm run build
  • Check tsconfig.json settings
  • Verify all dependencies are installed

Package Structure

The published package includes:

dist/
  ├── index.js          # Compiled JavaScript
  ├── index.d.ts        # TypeScript definitions
  ├── generator.js
  ├── generator.d.ts
  ├── types.js
  └── types.d.ts
README.md
LICENSE
package.json

Source files (src/) are excluded via .npmignore.

Version Management

Consider using npm version for version management:

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

This automatically:

  • Updates package.json version
  • Creates a git commit
  • Creates a git tag (if in a git repo)

Then publish with: npm publish