Skip to content

PUBLISHING.md

Latest commit

 

History

History
273 lines (187 loc) · 5.79 KB

PUBLISHING.md

File metadata and controls

273 lines (187 loc) · 5.79 KB

📦 NPM Publishing Guide for ngx-smart-tooltip

This guide will help you publish your library to npm.

✅ Pre-Publishing Checklist

Before publishing, ensure you have completed the following:

  • README.md - Comprehensive documentation with examples
  • package.json - Complete metadata with keywords, author, repository, homepage
  • LICENSE - MIT License file
  • CHANGELOG.md - Version history and release notes
  • .npmignore - Exclude unnecessary files from npm package
  • ng-package.json - Configured to include README, LICENSE, and CHANGELOG

🚀 Publishing Steps

1. Verify Node.js Version

Ensure you're using Node.js v20.19+ or v22.12+:

node --version

If you need to update Node.js, use nvm:

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 20
nvm install 20
nvm use 20

2. Build the Library

Build the production version of your library:

npm run build:prod

This will create the distributable files in dist/ngx-smart-tooltip/.

3. Verify the Build

Check the contents of the dist folder:

cd dist/ngx-smart-tooltip
ls -la

You should see:

  • README.md - Your library documentation
  • LICENSE - MIT License
  • CHANGELOG.md - Version history
  • package.json - Package metadata
  • fesm2022/ - ES modules
  • types/ - TypeScript definitions

4. Test the Package Locally (Optional but Recommended)

Before publishing, test the package locally:

# Create a tarball
npm pack

# This creates ngx-smart-tooltip-1.0.0.tgz
# You can install this in a test project:
# npm install /path/to/ngx-smart-tooltip-1.0.0.tgz

5. Login to NPM

If you haven't already, create an npm account at npmjs.com.

Then login via CLI:

npm login

Enter your:

  • Username
  • Password
  • Email
  • One-time password (if 2FA is enabled)

6. Publish to NPM

From the workspace root, run:

npm run publish:npm

Or manually:

# Build first
npm run build:prod

# Navigate to dist folder
cd dist/ngx-smart-tooltip

# Publish
npm publish

For first-time publishing a scoped package, you may need to make it public:

npm publish --access public

7. Verify Publication

After publishing, verify your package:

  1. Visit: https://www.npmjs.com/package/ngx-smart-tooltip
  2. Check that all metadata is correct
  3. Verify README displays properly
  4. Test installation in a new project:
npm install ngx-smart-tooltip

🔄 Publishing Updates

When publishing updates:

1. Update Version

Use semantic versioning:

# Patch release (1.0.0 -> 1.0.1) - Bug fixes
npm version patch

# Minor release (1.0.0 -> 1.1.0) - New features, backward compatible
npm version minor

# Major release (1.0.0 -> 2.0.0) - Breaking changes
npm version major

This will automatically:

  • Update package.json version
  • Create a git commit
  • Create a git tag

2. Update CHANGELOG.md

Document your changes in CHANGELOG.md following the existing format.

3. Commit and Push

git add .
git commit -m "chore: release v1.0.1"
git push origin main --tags

4. Publish

npm run publish:npm

📊 Post-Publishing Tasks

After successful publication:

1. Create GitHub Release

  1. Go to: https://github.com/techasif/ngx-smart-tooltip/releases/new
  2. Select the version tag (e.g., v1.0.0)
  3. Title: v1.0.0 - Initial Release
  4. Description: Copy from CHANGELOG.md
  5. Publish release

2. Update Documentation

Ensure your demo site is up to date:

3. Announce

Share your library:

  • Twitter/X with hashtags: #Angular #TypeScript #OpenSource
  • Reddit: r/angular, r/typescript
  • Dev.to article
  • Angular Discord/Slack communities
  • LinkedIn

4. Add Badges to README

Your README already includes badges that will automatically update:

  • npm version
  • npm downloads
  • bundle size
  • license

🛠️ Troubleshooting

"You do not have permission to publish"

Make sure you're logged in to the correct npm account:

npm whoami

"Package name already exists"

The package name ngx-smart-tooltip must be unique. If taken, you'll need to:

  1. Choose a different name, or
  2. Use a scoped package: @yourusername/ngx-smart-tooltip

"Version already published"

You cannot republish the same version. Increment the version:

npm version patch

Build Errors

Ensure you're using the correct Node.js version (20.19+ or 22.12+):

node --version

📝 Best Practices

  1. Always test locally before publishing
  2. Use semantic versioning correctly
  3. Keep CHANGELOG.md updated with every release
  4. Write meaningful commit messages
  5. Tag releases in git
  6. Create GitHub releases for major versions
  7. Respond to issues and PRs promptly
  8. Keep dependencies updated
  9. Monitor bundle size - keep it small!
  10. Gather feedback from users

🎯 Success Metrics

Track your library's success:

🎉 You're Ready!

Your library is now professionally configured and ready for npm publication. Good luck! 🚀

Need Help?