astro-discovery/PUBLISHING.md

# Publishing @astrojs/discovery to npm

This guide walks through publishing the package to npm.

## Prerequisites

### 1. npm Account Setup

```bash
# 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**
```bash
# Change package name to: @yourusername/astro-discovery
npm init scope @yourusername
```

**C. Publish without scope**
```bash
# Change package name to: astro-discovery
# Simpler, no permissions needed
```

### 3. Repository Setup

```bash
# 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

- [x] All tests passing (89/89 tests ✓)
- [x] TypeScript compilation successful
- [x] No lint errors
- [x] Build generates correct dist/ structure

### ✅ Documentation

- [x] README.md complete
- [x] LICENSE file (MIT)
- [ ] CHANGELOG.md updated for v1.0.0
- [x] Comprehensive Starlight docs site

### ✅ Package Configuration

- [x] package.json metadata complete
- [x] Keywords optimized for discovery
- [ ] Repository URL verified
- [x] Files field configured (only ships dist/)
- [x] Exports configured correctly
- [x] 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

```bash
# Edit CHANGELOG.md with v1.0.0 release notes
```

### 2. Update package.json Repository

```bash
# Edit package.json repository field to your actual repo
```

### 3. Dry Run (Preview)

```bash
# 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)

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

### 5. Commit Everything

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

### 6. Create Git Tag

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

### 7. Publish to npm

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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.)

```bash
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.)

```bash
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.)

```bash
# 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](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
- [npm Provenance](https://docs.npmjs.com/generating-provenance-statements)
- [Astro Integrations](https://astro.build/integrations/)
- [Semantic Versioning](https://semver.org/)