NPM Publishing Guide

This guide explains how to publish CSP Kit packages to NPM, including setup, versioning, and release procedures.

Prerequisites
Package Configuration
Publishing Process
Automated Publishing
Manual Publishing
Verification
Troubleshooting

Prerequisites

NPM Account Setup

Create NPM Account: Register at npmjs.com
Enable 2FA: Set up two-factor authentication for security
Get Access Token: Generate automation token for CI/CD

# Login to NPM
npm login

# Verify login
npm whoami

# Generate automation token (for CI/CD)
npm token create --type=automation

Repository Permissions

Ensure you have:

Write access to the GitHub repository
Admin access to NPM packages
Maintainer role for @csp-kit organization

Package Configuration

Package.json Setup

All packages are configured with proper NPM publishing settings:

{
  "name": "@csp-kit/generator",
  "version": "1.0.0",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/",
    "provenance": true
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/eason-dev/csp-kit.git",
    "directory": "packages/generator"
  },
  "scripts": {
    "prepare": "npm run build",
    "prepack": "npm run build && npm run test",
    "prepublishOnly": "npm run lint && npm run check-types"
  }
}

Files Configuration

Each package includes only necessary files:

{
  "files": ["dist", "README.md", "CHANGELOG.md"]
}

NPM Configuration

Root .npmrc configuration:

# NPM Configuration
registry=https://registry.npmjs.org/
access=public
fund=true
save-exact=true

# Workspace settings
link-workspace-packages=true
shared-workspace-lockfile=true

# Security settings
audit-level=moderate
package-lock=false

# Publishing settings
provenance=true

# Development settings
engine-strict=true
auto-install-peers=true

Publishing Process

Package Dependencies

Packages must be published in dependency order:

@csp-kit/data (no dependencies)
@csp-kit/generator (depends on @csp-kit/data)
@csp-kit/cli (depends on @csp-kit/data)

Version Management

CSP Kit uses synchronized versioning - all packages share the same version number:

# Check current versions
node -p "require('./packages/generator/package.json').version"
node -p "require('./packages/data/package.json').version"
node -p "require('./packages/cli/package.json').version"

# Update all package versions
pnpm version:patch   # 1.0.0 → 1.0.1
pnpm version:minor   # 1.0.1 → 1.1.0
pnpm version:major   # 1.1.0 → 2.0.0

Automated Publishing

GitHub Actions Release

The preferred method is using GitHub Actions for automated publishing:

Create Release Tag:
```
git tag v1.0.0
git push origin v1.0.0
```
Monitor Release:
- Go to Actions tab
- Watch the "Release" workflow
- Check for any failures
Verify Publication:
- Check NPM packages
- Verify GitHub release created
- Test installation

Release Workflow Steps

The automated release workflow:

Validation:
- Extract version from tag
- Determine if prerelease
- Validate package structure
Testing:
- Run full test suite
- Type checking
- Linting
- Security audit
Building:
- Build all packages
- Verify artifacts
- Test package imports
Publishing:
- Publish to NPM with provenance
- Create GitHub release
- Update documentation
Verification:
- Test NPM installation
- Verify CLI functionality
- Check package availability

Manual Publishing

Using Publishing Script

For manual releases, use the publishing script:

# Dry run to see what would happen
./scripts/publish.sh --dry-run

# Publish patch release
./scripts/publish.sh patch

# Publish minor release
./scripts/publish.sh minor

# Publish major release
./scripts/publish.sh major

# Skip tests (not recommended)
./scripts/publish.sh patch --skip-tests

Manual Step-by-Step

If the script fails, you can publish manually:

Pre-flight Checks:

# Validate everything is ready
node scripts/validate-release.js

Update Versions:

# Update package versions
cd packages/data && npm version 1.0.0 --no-git-tag-version
cd ../generator && npm version 1.0.0 --no-git-tag-version
cd ../cli && npm version 1.0.0 --no-git-tag-version

Build Packages:
```
pnpm build
```

Publish in Order:

# Publish data first
cd packages/data
npm publish --access public --provenance

# Wait for NPM propagation
sleep 30

# Publish generator
cd ../generator
npm publish --access public --provenance

# Wait for NPM propagation
sleep 30

# Publish cli
cd ../cli
npm publish --access public --provenance

Create Git Tag:

git add .
git commit -m "chore(release): v1.0.0"
git tag v1.0.0
git push origin main v1.0.0

Verification

Post-Publication Checks

After publishing, verify the release:

NPM Package Availability:

# Check packages are available
npm view @csp-kit/generator
npm view @csp-kit/data
npm view @csp-kit/cli

# Check specific version
npm view @csp-kit/generator@1.0.0

Installation Test:

# Test installation in clean environment
mkdir test-install && cd test-install
npm init -y
npm install @csp-kit/generator@1.0.0

# Test functionality
node -e "
  const { generateCSP } = require('@csp-kit/generator');
  console.log(generateCSP(['google-analytics']).header);
"

CLI Test:

# Test global CLI installation
npm install -g @csp-kit/cli@1.0.0
@csp-kit/cli --version
@csp-kit/cli generate google-analytics

Documentation Verification:
- Check GitHub release page
- Verify README badges are updated
- Confirm documentation links work

Package Health Checks

Monitor package health after release:

# Check download stats
npm view @csp-kit/generator dist-tags
npm view @csp-kit/generator time

# Monitor for issues
npm audit @csp-kit/generator
npm outdated @csp-kit/generator

Troubleshooting

Common Publishing Issues

Authentication Errors

# Error: You must be logged in to publish packages
npm login

# Error: You do not have permission to publish
# Contact package owner to add you as maintainer

Version Conflicts

# Error: Version already exists
# Increment version number
npm version patch

# Error: Version not in sync
# Use the publishing script to sync versions
./scripts/publish.sh patch

Build Failures

# Error: Build artifacts missing
pnpm build

# Error: Tests failing
pnpm test

# Error: Type errors
pnpm check-types

NPM Registry Issues

# Error: Package not found after publishing
# Wait for NPM propagation (up to 15 minutes)
sleep 300

# Error: Package shows old version
# Clear NPM cache
npm cache clean --force

Emergency Procedures

Unpublish Package

# Unpublish specific version (within 24 hours)
npm unpublish @csp-kit/generator@1.0.0

# Deprecate version (after 24 hours)
npm deprecate @csp-kit/generator@1.0.0 "Critical bug - use 1.0.1 instead"

Rollback Release

# Publish fixed version
npm version patch
npm publish

# Update documentation
git commit -m "docs: update for emergency release"
git push

Support Channels

If you encounter issues:

Check GitHub Issues: Issues page
NPM Support: NPM Support
Contact Maintainers: Create issue with @maintainer tag

Publishing Checklist

Before each release:

After each release:

Last Updated: 2024-06-29 Guide Version: 1.0.0

Table of Contents​

Prerequisites​

NPM Account Setup​

Repository Permissions​

Package Configuration​

Package.json Setup​

Files Configuration​

NPM Configuration​

Publishing Process​

Package Dependencies​

Version Management​

Automated Publishing​

GitHub Actions Release​

Release Workflow Steps​

Manual Publishing​

Using Publishing Script​

Manual Step-by-Step​

Verification​

Post-Publication Checks​

Package Health Checks​

Troubleshooting​

Common Publishing Issues​

Authentication Errors​

Version Conflicts​

Build Failures​

NPM Registry Issues​

Emergency Procedures​

Unpublish Package​

Rollback Release​

Support Channels​

Publishing Checklist​

Table of Contents