~+
Supernal TTS

NPM Package Publishing Setup

This document explains how to set up automated NPM package publishing for the Supernal TTS family.

Overview

The project includes several publishable NPM packages:

  • supernal-tts-server - Production-ready TTS API server
  • supernal-tts-widget - Embeddable JavaScript widget
  • @supernal-tts/core - Core TTS functionality and providers
  • @supernal-tts/client - Client SDK for the TTS API
  • @supernal-tts/types - TypeScript type definitions
  • @supernal/api-usage-tracker - API usage tracking utilities

GitHub Secrets Setup

1. Create NPM Access Token

  1. Log in to npmjs.com
  2. Go to your profile → Access Tokens
  3. Click "Generate New Token"
  4. Choose "Automation" token type (for CI/CD)
  5. Copy the generated token

2. Add NPM_TOKEN to GitHub Secrets

  1. Go to your GitHub repository
  2. Navigate to Settings → Secrets and variables → Actions
  3. Click "New repository secret"
  4. Name: NPM_TOKEN
  5. Value: Paste your NPM access token
  6. Click "Add secret"

Publishing Workflow

The project uses GitHub Actions to automatically publish packages when you create a version tag:

# Create and push a version tag
./scripts/release.sh 1.2.3

# For pre-release versions
./scripts/release.sh 1.2.3-beta.1

# Dry run to test
./scripts/release.sh 1.2.3 --dry-run

Manual Publishing

You can also trigger publishing manually:

  1. Go to GitHub Actions → "Publish NPM Packages"
  2. Click "Run workflow"
  3. Optionally specify a version or enable dry-run mode

Package Publishing Details

Change Detection

The workflow automatically detects which packages have changed and only publishes those packages. This prevents unnecessary publishes and version bumps.

Version Management

  • Tagged releases: The version is extracted from the git tag (e.g., v1.2.3 → 1.2.3)
  • Manual workflow: You can specify a version in the workflow dispatch
  • Default: Uses the version in each package's package.json

Publishing Order

Packages are published in dependency order:

  1. @supernal-tts/types (base types)
  2. @supernal-tts/core (depends on types)
  3. @supernal-tts/client (depends on types)
  4. @supernal/api-usage-tracker (independent)
  5. supernal-tts-server (independent)
  6. supernal-tts-widget (independent)

Access Control

All packages are published with --access public to ensure they're publicly available on NPM.

Release Process

1. Prepare Release

# Ensure you're on main branch
git checkout main
git pull origin main

# Run tests
npm test

# Build packages
npm run build:packages

2. Create Release

# Use the release script (recommended)
./scripts/release.sh 1.2.3

# Or manually create tag
git tag v1.2.3
git push origin v1.2.3

3. Monitor Publishing

  1. Check GitHub Actions workflow: https://github.com/your-org/supernal-tts/actions
  2. Verify packages on NPM:

Troubleshooting

Publishing Fails

  1. NPM Token Issues:

    • Verify NPM_TOKEN secret is set correctly
    • Ensure token has publishing permissions
    • Check token hasn't expired

  2. Version Conflicts:

    • Ensure version doesn't already exist on NPM
    • Use semantic versioning format (x.y.z)

  3. Build Failures:

    • Check TypeScript compilation errors
    • Verify all dependencies are installed
    • Ensure tests pass

Package Not Publishing

  1. No Changes Detected:

    • The workflow only publishes packages with changes
    • Use manual workflow dispatch to force publishing

  2. Dependency Issues:

    • Ensure workspace dependencies are properly configured
    • Check that built packages exist in dist/ directories

Package Configuration

Each package includes:

  • Repository URL: Points to the monorepo with directory specification
  • Publishing Config: "access": "public" for public packages
  • Files Array: Specifies which files to include in the published package
  • Proper Metadata: Description, keywords, author, license

Security Notes

  • NPM tokens are stored as GitHub secrets and never exposed in logs
  • Packages are published with public access
  • All packages include proper repository and bug tracking URLs
  • License information is included in all packages