# Publishing HIS.js to npm

This guide walks through publishing `@his-js/core` to npm.

## Prerequisites

1. **npm Account**: Create one at [npmjs.com](https://www.npmjs.com/signup)
2. **npm CLI**: Installed with Node.js
3. **Authentication**: Login to npm

## Step 1: Prepare for Publishing

### Login to npm

```bash
npm login
```

Enter your:
- Username
- Password  
- Email
- Two-factor authentication code (if enabled)

### Verify Login

```bash
npm whoami
```

## Step 2: Update Package Details

Edit `package.json`:

```json
{
  "name": "@your-username/his-js",
  "version": "1.0.0",
  "author": "Your Name <your.email@example.com>",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/his-js.git"
  }
}
```

**Note**: For scoped packages (`@username/package`), you can publish for free!

## Step 3: Build the Package

```bash
npm install
npm run build
```

This creates the `dist/` directory with:
- `index.js` (CommonJS)
- `index.mjs` (ESM)
- `index.d.ts` (TypeScript types)

## Step 4: Test Locally

### Test the Build

```bash
npm test
```

### Test Installation Locally

```bash
npm pack
```

This creates a `.tgz` file. Test it:

```bash
mkdir test-install
cd test-install
npm install ../his-js-core-1.0.0.tgz
node -e "const HisJS = require('@his-js/core'); console.log(HisJS)"
```

## Step 5: Publish

### Dry Run (Recommended First)

```bash
npm publish --dry-run
```

This shows what will be published without actually publishing.

### Publish to npm

For scoped packages (like `@his-js/core`):

```bash
npm publish --access public
```

For unscoped packages:

```bash
npm publish
```

## Step 6: Verify Publication

1. Visit: `https://www.npmjs.com/package/@his-js/core`
2. Check version number
3. Review README rendering
4. Test installation:

```bash
npm install @his-js/core
```

## Version Management

### Update Version

Follow [Semantic Versioning](https://semver.org/):

- **Patch**: Bug fixes → `1.0.0` → `1.0.1`
  ```bash
  npm version patch
  ```

- **Minor**: New features (backward compatible) → `1.0.0` → `1.1.0`
  ```bash
  npm version minor
  ```

- **Major**: Breaking changes → `1.0.0` → `2.0.0`
  ```bash
  npm version major
  ```

This automatically:
- Updates `package.json`
- Creates a git commit
- Creates a git tag

### Publish New Version

```bash
git push && git push --tags
npm publish --access public
```

## Automation (Optional)

### Using GitHub Actions

The included `.github/workflows/ci.yml` automatically:
1. Tests on multiple Node versions
2. Tests on multiple OS (Linux, Windows, macOS)
3. Publishes to npm on push to `main`

**Setup**:
1. Create npm access token: https://www.npmjs.com/settings/your-username/tokens
2. Add to GitHub Secrets: `Settings` → `Secrets` → `NPM_TOKEN`

## Troubleshooting

### "Package already exists"

The package name is taken. Choose a different name:
- Use scoped package: `@your-username/his-js`
- Use different name: `his-logger`, `ai-history-js`, etc.

### "You must verify your email"

Check your npm email and verify it.

### "You do not have permission to publish"

For scoped packages, add `--access public`:
```bash
npm publish --access public
```

### "402 Payment Required"

Scoped packages require `--access public` flag for free publishing.

### ".npmignore not working"

Files are published based on:
1. `files` field in `package.json` (whitelist)
2. `.npmignore` (blacklist)
3. `.gitignore` (fallback blacklist)

Check `files` field is correct.

## Best Practices

1. **Always test locally first** with `npm pack`
2. **Use semantic versioning** consistently
3. **Update CHANGELOG.md** for each version
4. **Tag releases** in git
5. **Test installation** after publishing
6. **Monitor for issues** on npm and GitHub

## Unpublishing (Emergency Only)

You can unpublish within 72 hours:

```bash
npm unpublish @his-js/core@1.0.0
```

**Warning**: This is discouraged. Use deprecation instead:

```bash
npm deprecate @his-js/core@1.0.0 "Use version 1.0.1 instead"
```

## Support

- npm docs: https://docs.npmjs.com/
- npm support: https://www.npmjs.com/support
- GitHub Issues: https://github.com/your-username/his-js/issues

## Next Steps

After publishing:

1. ⭐ Add npm badge to README
2. 📝 Write a blog post announcement
3. 🐦 Tweet about it
4. 📢 Share on Reddit, Dev.to, etc.
5. 📊 Set up download analytics
6. 🔔 Monitor GitHub issues

Congratulations on publishing HIS.js! 🎉