# Publishing to npm - Step by Step Guide

## Current Status
- **Current npm version**: 1.0.4
- **New version**: 2.0.0 (major version bump)
- **Status**: Not logged in to npm

## Pre-Publishing Checklist

### 1. Verify Package Contents
Make sure your `.npmignore` is correct (it should exclude `src/` since we publish built files):
```bash
cat .npmignore
# Should show: *.log, yarn.lock, src
```

### 2. Build the Package
Ensure the package is built before publishing:
```bash
npm run build
```

This will compile `src/` files to the root directory (gatsby-node.js, fetch.js, normalize.js).

### 3. Verify Built Files
Check that the built files exist:
```bash
ls -la *.js
# Should show: index.js, gatsby-node.js, fetch.js, normalize.js
```

### 4. Test the Package Locally (Optional but Recommended)
Test the package locally before publishing:
```bash
npm pack
# This creates a .tgz file you can test
```

Then in a test project:
```bash
npm install /path/to/gatsby-source-greenhouse-job-board/gatsby-source-greenhouse-job-board-2.0.0.tgz
```

## Publishing Steps

### Step 1: Login to npm
```bash
npm login
```

You'll be prompted for:
- Username
- Password
- Email (if not already set)
- One-time password (if 2FA is enabled)

Verify you're logged in:
```bash
npm whoami
```

### Step 2: Verify Package.json
Double-check your `package.json`:
- ✅ Version is `2.0.0`
- ✅ Name is correct: `gatsby-source-greenhouse-job-board`
- ✅ All required fields are present

### Step 3: Build the Package
```bash
npm run build
```

### Step 4: Dry Run (Recommended)
Test what will be published without actually publishing:
```bash
npm publish --dry-run
```

This will show you:
- What files will be included
- Package size
- Any warnings

### Step 5: Publish to npm
```bash
npm publish
```

For a scoped package (if you have one), you might need:
```bash
npm publish --access public
```

### Step 6: Verify Publication
Check that the new version is on npm:
```bash
npm view gatsby-source-greenhouse-job-board version
# Should show: 2.0.0
```

Or visit: https://www.npmjs.com/package/gatsby-source-greenhouse-job-board

## Post-Publishing

### 1. Create Git Tag (Recommended)
Tag the release in git:
```bash
git tag v2.0.0
git push origin v2.0.0
```

Or create an annotated tag:
```bash
git tag -a v2.0.0 -m "Release v2.0.0 - Modernize for Gatsby 5"
git push origin v2.0.0
```

### 2. Update GitHub Release (Optional)
If you use GitHub releases, create a new release pointing to the v2.0.0 tag with:
- Release notes from BREAKING_CHANGES.md
- Link to migration guide in README.md

## Troubleshooting

### "You cannot publish over the existing version"
- Make sure version in package.json is actually 2.0.0
- Check npm: `npm view gatsby-source-greenhouse-job-board versions`

### "You do not have permission"
- Verify you're the package owner: `npm owner ls gatsby-source-greenhouse-job-board`
- If not, ask the current owner to add you: `npm owner add <your-username> gatsby-source-greenhouse-job-board`

### "Package name already exists"
- This shouldn't happen if you're updating your own package
- Verify you're logged in as the correct user

### Build files missing
- Make sure `npm run build` completed successfully
- Check that `.npmignore` doesn't exclude the built files
- Verify `package.json` has `"main": "index.js"` pointing to the correct file

## Quick Reference Commands

```bash
# Full publishing workflow
npm run build                    # Build the package
npm publish --dry-run           # Test what will be published
npm publish                     # Publish to npm
npm view gatsby-source-greenhouse-job-board version  # Verify

# Git tagging
git tag v2.0.0
git push origin v2.0.0
```

## Notes

- The `prepare` script in package.json will automatically run `npm run build` when the package is installed, so users will get the built files
- However, it's best practice to publish the built files to npm for faster installs
- Your `.npmignore` correctly excludes `src/` so only built files are published
- The `package.json` `files` field (if present) or `.npmignore` controls what gets published