astro-discovery/PUBLISHING.md

Publishing @astrojs/discovery to npm

This guide walks through publishing the package to npm.

Prerequisites

1. npm Account Setup

# Create npm account (if needed)
# Visit: https://www.npmjs.com/signup

# Login to npm
npm login

# Enable 2FA (REQUIRED for publishing to org scopes)
npm profile enable-2fa auth-and-writes

2. Scope Decision

Current package name: @astrojs/discovery

Options:

A. Publish under @astrojs (requires Astro team approval)

• Contact Astro team first
• Need to be added to @astrojs npm organization
• Best for official integrations

B. Publish under your own scope

# Change package name to: @yourusername/astro-discovery
npm init scope @yourusername

C. Publish without scope

# Change package name to: astro-discovery
# Simpler, no permissions needed

3. Repository Setup

# Create GitHub repository
gh repo create astro-discovery --public

# Add remote
git remote add origin https://github.com/yourusername/astro-discovery.git

# Push code
git push -u origin main

# Update package.json repository field to match

Pre-Publish Checklist

✅ Code Quality

• All tests passing (89/89 tests ✓)
• TypeScript compilation successful
• No lint errors
• Build generates correct dist/ structure

✅ Documentation

• README.md complete
• LICENSE file (MIT)
• CHANGELOG.md updated for v1.0.0
• Comprehensive Starlight docs site

✅ Package Configuration

• package.json metadata complete
• Keywords optimized for discovery
• Repository URL verified
• Files field configured (only ships dist/)
• Exports configured correctly
• prepublishOnly hook configured

✅ Version Strategy

Current version: 1.0.0

Date-based versioning (as per CLAUDE.md guidelines):

• Use YYYY-MM-DD for backwards-incompatible changes
• Example: 2025-12-22 for next major breaking change

For now, semantic versioning is fine for 1.0.0 launch.

Publishing Steps

1. Update CHANGELOG

# Edit CHANGELOG.md with v1.0.0 release notes

2. Update package.json Repository

# Edit package.json repository field to your actual repo

3. Dry Run (Preview)

# See what will be included in the package
npm pack --dry-run

# This creates a tarball you can inspect
npm pack
tar -tzf astrojs-discovery-1.0.0.tgz
rm astrojs-discovery-1.0.0.tgz

4. Test Publish (Dry Run)

# Simulate publishing without actually doing it
npm publish --dry-run

5. Commit Everything

# Commit any final changes
git add -A
git commit -m "chore: prepare v1.0.0 release"
git push

6. Create Git Tag

# Tag the release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

7. Publish to npm

# Publish with provenance (recommended)
npm publish --provenance --access public

# Or without provenance
npm publish --access public

Note: --access public is required for scoped packages to make them public.

8. Create GitHub Release

# Using gh CLI
gh release create v1.0.0 \
  --title "v1.0.0" \
  --notes "Initial release of @astrojs/discovery integration"

# Or manually on GitHub
# Visit: https://github.com/yourusername/astro-discovery/releases/new

9. Verify Publication

# Check it's live
npm view @astrojs/discovery

# Test installation
mkdir test-install
cd test-install
npm init -y
npm install @astrojs/discovery

Post-Publishing

1. Update Documentation Site

Deploy the Starlight docs to Vercel/Netlify:

cd docs
# Deploy to Vercel
vercel --prod

# Or Netlify
netlify deploy --prod

2. Announce

• Tweet/post about the release
• Share in Astro Discord
• Consider submitting to Astro integrations directory

3. Monitor

• Watch for issues on GitHub
• Monitor npm download stats
• Respond to community feedback

Subsequent Releases

Patch Release (1.0.1, 1.0.2, etc.)

npm version patch
git push && git push --tags
npm publish --provenance --access public
gh release create v1.0.1 --generate-notes

Minor Release (1.1.0, 1.2.0, etc.)

npm version minor
git push && git push --tags
npm publish --provenance --access public
gh release create v1.1.0 --generate-notes

Major Release (2.0.0, etc.)

# Update CHANGELOG with breaking changes
npm version major
git push && git push --tags
npm publish --provenance --access public
gh release create v2.0.0 --notes "Breaking changes: ..."

Troubleshooting

"You do not have permission to publish"

• Verify you're logged in: npm whoami
• Check 2FA is enabled
• Verify scope permissions if using @astrojs

"Package name already exists"

• Choose different name or scope
• Contact existing package owner

"prepublishOnly script failed"

• Ensure all tests pass: npm test
• Verify build works: npm run build
• Check TypeScript compilation: tsc --noEmit

npm Provenance

Recommended: Use --provenance flag when publishing.

Benefits:

• Cryptographically links package to source code
• Increases trust and security
• Verifiable build attestation
• Required by GitHub when publishing from Actions

Requires:

• Publishing from a supported CI environment (GitHub Actions)
• Or using npm CLI v9.5.0+ with properly configured environment

References

• npm Publishing Guide
• npm Provenance
• Astro Integrations
• Semantic Versioning