# npm Publication Guide - React Magnifier v1.3.0

**Date**: July 29, 2026  
**Status**: Ready for Publication  
**Version**: 1.3.0

---

## ✅ Pre-Publication Verification

Before publishing, verify all systems are operational:

### Step 1: Verify Build

```bash
npm run build
```

Expected output:

```
✓ 4 modules transformed by @vitejs/plugin-react
dist/react-magnifier.js          16.10 kB │ gzip: 3.74 kB
dist/react-magnifier.umd.cjs     8.03 kB │ gzip: 2.87 kB
dist/index.d.ts                      ~2 kB
```

**Verification**: ✅ Build size matches expected (~3.74 kB gzipped ESM)

### Step 2: Verify Tests

```bash
npm test -- --run
```

Expected output (v1.3.0 — 50 tests):

```
✓ tests passed (all 3 suites)
Tests      50 passed (50)
```

**Verification**: ✅ All 50 tests passing

### Step 3: Verify TypeScript

```bash
npm run type-check
```

Expected output:

```
No TypeScript errors found.
```

**Verification**: ✅ 0 TypeScript errors

### Step 4: Verify Linting

```bash
npm run lint
```

Expected output:

```
No critical errors found.
```

**Verification**: ✅ No critical linting issues

---

## 📦 Package Configuration Review

### Current package.json Settings

```json
{
  "name": "@sandeepv68/react-magnifier",
  "version": "1.3.0",
  "type": "module",
  "main": "./dist/react-magnifier.umd.cjs",
  "module": "./dist/react-magnifier.js",
  "types": "./dist/index.d.ts",
  "description": "A performant, accessible React component for image magnification",
  "keywords": [...],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/SandeepVattapparambil/react-magnify"
  },
  "homepage": "https://github.com/SandeepVattapparambil/react-magnify#readme",
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "styled-components": "^6.0.0"
  },
  "exports": {
    ".": {
      "import": "./dist/react-magnifier.js",
      "require": "./dist/react-magnifier.umd.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}
```

**Status**: ✅ Configured correctly for npm publication

---

## 🔐 npm Account Requirements

### Prerequisites

1. ✅ npm account created at https://www.npmjs.com
2. ✅ Local npm login: `npm login`
3. ✅ Scoped package: `@sandeepv68/react-magnifier` (must match npm username)
4. ✅ MFA enabled (recommended)
5. ✅ Access token configured (if using CI/CD)

### Account Verification

```bash
npm whoami
# Output should show your npm username
```

---

## 🚀 Publication Workflow

### Option A: Recommended Workflow (with Git)

#### Step 1: Git Commit

```bash
# Stage all changes
git add .

# Commit with descriptive message
git commit -m "feat: v1.3.0 - forwardRef, useId, prop renames, dev tooling

- Add React.forwardRef support with exported types
- Add React 19 useId() for unique ARIA IDs
- Rename customImgStyles → customImgClass, customContainerStyles → customContainerClass
- Fix keyboard bounds clamping, getCursorPos scroll calc, PIXEL_PADDING
- Configure Husky pre-commit hooks with lint-staged
- Comprehensive TSDoc/JSDoc comments across all source files"
```

#### Step 2: Create Git Tag

```bash
git tag -a v1.3.0 -m "React Magnifier v1.3.0: forwardRef, useId, prop renames, bug fixes

BREAKING CHANGES: None (100% backward compatible with deprecation notices)
NEW FEATURES:
- React.forwardRef support (container div ref forwarding)
- React 19 useId() for unique ARIA IDs (no duplicate ID violations)
- Renamed customImgStyles → customImgClass, customContainerStyles → customContainerClass
- Husky pre-commit hooks with lint-staged
- Comprehensive TSDoc/JSDoc comments on all source files

BUG FIXES:
- Keyboard bounds clamping (arrow keys stay within image boundaries)
- getCursorPos scroll calculation (clientX/clientY instead of pageX/pageY)
- PIXEL_PADDING replaced with magnifierBorderWidth

IMPROVEMENTS:
- Bundle size: 6.29 kB → 3.74 kB gzipped ESM
- Removed redundant useMemo, empty scripts/, duplicate build:lib script, .npmrc
- Updated @testing-library/react to 16.3.2

See RELEASE_NOTES.md for full details"
```

#### Step 3: Push to GitHub

```bash
# Push commits
git push origin main

# Push tags
git push origin v1.3.0

# Or push all tags at once
git push origin --tags
```

#### Step 4: Create GitHub Release

1. Go to: https://github.com/SandeepVattapparambil/react-magnify/releases
2. Click "Draft a new release"
3. Choose tag: v1.3.0
4. Release title: "React Magnifier v1.3.0 - forwardRef, useId, prop renames, bug fixes"
5. Copy description from RELEASE_NOTES.md
6. Click "Publish release"

#### Step 5: npm Publication

```bash
# Verify you're in the correct directory
pwd  # Should be /path/to/react-magnify

# Verify build artifacts exist
ls -la dist/

# Publish to npm (public access for scoped package)
npm publish --access public
```

Expected output:

```
npm notice
npm notice 📦 @sandeepv68/react-magnifier@1.3.0
npm notice === Tarball Contents ===
npm notice 1.2 kB  package.json
npm notice 5.8 kB  README.md
npm notice 1.1 kB  LICENSE
npm notice 16.1 kB dist/react-magnifier.js
npm notice 8.0 kB  dist/react-magnifier.umd.cjs
...
npm notice === Tarball Details ===
npm notice name:          @sandeepv68/react-magnifier
npm notice version:       1.3.0
npm notice package size:  ~35 kB
npm notice unpacked size: ~140 kB
npm notice shasum:        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npm notice integrity:     sha512-...
npm notice total files:   15
npm notice
npm notice Publishing to registry.npmjs.org with tag latest and default access
```

#### Step 6: Post-Publication Verification

```bash
# Verify package published
npm view @sandeepv68/react-magnifier

# Should output:
# @sandeepv68/react-magnifier@1.3.0 | MIT | deps: none | dist
# A performant, accessible React component for image magnification
```

---

### Option B: Direct Publication (without Git)

If you prefer to publish without creating a git tag:

```bash
# Ensure build is ready
npm run build

# Verify tests
npm test -- --run

# Publish directly
npm publish --access public
```

**Note**: It's recommended to use Option A for better version tracking.

---

## 🔍 Post-Publication Verification

### Verify Package Published

```bash
# Search for package
npm search react-magnifier

# Or view package details
npm view @sandeepv68/react-magnifier

# Should show v1.3.0 as latest
```

### Verify Installation in New Project

```bash
# Create a test directory
mkdir test-install && cd test-install

# Initialize npm
npm init -y

# Install React and React-DOM
npm install react react-dom

# Install the published package
npm install @sandeepv68/react-magnifier

# Check installed version
npm list @sandeepv68/react-magnifier

# Should show: @sandeepv68/react-magnifier@1.3.0
```

### Verify Package Contents

```bash
# View what will be published
npm pack --dry-run

# Or generate the tarball
npm pack

# Extract and inspect
tar -tzf sandeepv68-react-magnifier-1.3.0.tgz | head -20
```

### Verify TypeScript Types

```bash
# In a test project with TypeScript
npm install typescript @types/react @types/react-dom

# Create test.ts
cat > test.ts << 'EOF'
import ReactMagnifier from '@sandeepv68/react-magnifier';

const props: React.ComponentProps<typeof ReactMagnifier> = {
  imageUrl: 'image.jpg'
};
EOF

# Check TypeScript can find types
npx tsc --noEmit test.ts

# Should have no errors
```

---

## 🆘 Troubleshooting

### Issue: "npm ERR! 403 Forbidden"

**Cause**: Publishing to wrong registry or insufficient permissions

**Solution**:

```bash
# Check current registry
npm config get registry
# Should output: https://www.npmjs.com/

# Login again
npm login

# Verify login
npm whoami
# Should show your npm username
```

### Issue: "npm ERR! You must be logged in to publish"

**Solution**:

```bash
# Login to npm
npm login

# Enter email, password, OTP (if MFA enabled)
npm whoami  # Verify logged in
npm publish --access public
```

### Issue: "npm ERR! Package name already exists"

**Cause**: Package name taken by another user

**Solution**: Use a different scoped name or unscoped name

```bash
# Check if name is available
npm view @your-username/react-magnifier

# Update package.json if needed
{
  "name": "@your-unique-username/react-magnifier"
}

# Then republish
npm publish --access public
```

### Issue: "npm ERR! You do not have permission to publish"

**Cause**: Scoped package requires organization permissions

**Solution**:

```bash
# Publish with explicit access flag
npm publish --access public

# Or create org and add yourself
npm org members add username
```

### Issue: Build artifacts missing in dist/

**Cause**: Build not run before publish

**Solution**:

```bash
# Clean build
rm -rf dist node_modules
npm install
npm run build

# Verify dist/ exists
ls dist/

# Then publish
npm publish --access public
```

---

## 📋 Publication Checklist

Before publishing, verify all items:

### Code Quality

- ✅ `npm run type-check` passes (0 errors)
- ✅ `npm run lint` passes (2 demo-only warnings)
- ✅ `npm run build` completes (~4s)
- ✅ `npm test -- --run` passes (50 tests)

### Package Configuration

- ✅ package.json version is 1.3.0
- ✅ Main entry point correct: dist/react-magnifier.umd.cjs
- ✅ Module entry point correct: dist/react-magnifier.js
- ✅ Types entry point correct: dist/index.d.ts
- ✅ Files field includes dist/, README, LICENSE
- ✅ Peer dependencies correct: react, react-dom, styled-components
- ✅ `ReactMagnifierProps` type exported

### Distribution Files

- ✅ dist/react-magnifier.js exists (ESM, 16.10 kB)
- ✅ dist/react-magnifier.umd.cjs exists (UMD, 8.03 kB)
- ✅ dist/index.d.ts exists (TypeScript types)
- ✅ dist/*.map files exist (source maps)

### Documentation

- ✅ README.md exists and complete
- ✅ LICENSE file exists (MIT)
- ✅ CHANGELOG.md exists
- ✅ All links in README are working
- ✅ TSDoc/JSDoc comments on all source files

### Pre-flight

- ✅ npm whoami shows correct account
- ✅ npm config get registry shows npmjs.com
- ✅ No uncommitted changes (if using git)
- ✅ Latest code pushed to GitHub

### Publication

- [ ] git push origin main (if using git)
- [ ] git push origin v1.3.0 (if using git)
- [ ] Create GitHub release (if using GitHub)
- [ ] npm publish --access public

### Post-publication

- [ ] npm view @sandeepv68/react-magnifier shows v1.3.0
- [ ] Package visible on npmjs.com
- [ ] Installation works in new project
- [ ] TypeScript types resolve correctly
- [ ] GitHub release published

---

## 📊 Publication Success Criteria

✅ **Successfully Published When**:

1. npm publish completes without errors
2. Package appears on npmjs.com within 2-3 minutes
3. npm install @sandeepv68/react-magnifier installs v1.3.0
4. TypeScript types resolve correctly (ReactMagnifierProps exported)
5. Component imports and works in test app (forwardRef works)
6. GitHub release is visible on repository

---

## 🎉 What Happens After Publication

### Immediately (Minutes)

- ✅ Package available on npmjs.com
- ✅ npm install will find the package
- ✅ Developers can use in projects

### Short-term (Hours)

- ✅ Package indexed by search engines
- ✅ Appears in npm search results
- ✅ Available in IDE autocomplete
- ✅ GitHub shows release

### Long-term (Days)

- ✅ CDN mirrors get the package
- ✅ Community starts using it
- ✅ GitHub stars increase
- ✅ Real-world feedback arrives

---

## 📞 Publication Support

### NPM Registry Status

- Check: https://status.npmjs.org
- Support: https://npm.community

### npm Documentation

- Publishing: https://docs.npmjs.com/cli/publish
- Scoped packages: https://docs.npmjs.com/packages-and-modules/
- Security best practices: https://docs.npmjs.com/securing-your-npm-package

### GitHub Help

- Creating releases: https://docs.github.com/en/repositories/releasing-projects-on-github/
- Repository best practices: https://docs.github.com/en/repositories/

---

## 🎯 Recommended Publication Timeline

### T-0 (Before Publication)

- Run all verification steps
- Ensure all tests pass
- Verify build output
- Review package.json

### T-0:00 (Publication Time)

- Create git tag
- Push to GitHub
- Create GitHub release
- Run npm publish

### T+5min (Post-Publication)

- Verify package on npmjs.com
- Test installation in new project
- Verify TypeScript types

### T+1hour

- Monitor npm stats
- Check for any issues
- Announce on social media (if desired)

---

## ✨ Final Notes

### For First-time Publishers

- Take your time verifying everything
- Don't rush the publication process
- Test installation in a separate directory
- Verify TypeScript types resolve correctly
- Check package contents with `npm pack`

### Best Practices

- ✅ Always create a git tag for releases
- ✅ Create GitHub releases for better visibility
- ✅ Run all tests before publishing
- ✅ Include clear commit messages
- ✅ Update CHANGELOG.md before publishing
- ✅ Verify build artifacts before publishing

### After Publication

- ✅ Monitor for issues
- ✅ Be responsive to bug reports
- ✅ Plan v1.1 improvements (optional features)
- ✅ Keep documentation updated
- ✅ Consider adding badges to README

---

## 🚀 Ready to Publish!

All systems are go. React Magnifier v1.3.0 is ready for the world.

**Command to Publish**:

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

**Expected Time**: < 30 seconds  
**Expected Success Rate**: 99.9%

---

**Date**: July 29, 2026  
**Status**: ✅ READY FOR PUBLICATION  
**Recommendation**: Execute publication steps above 🚀

Good luck! Your component is production-ready! 🎉