gatsby-source-greenhouse-job-board/NPM_PUBLISH_GUIDE.md

Gatsby source plugin for pulling offices, departments, and jobs into Gatsby from the Greenhouse Job Board API. It creates links between offices, departments, and jobs so they can be queried in Gatsby using GraphQL.

# 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