Skip to content

GITHUB_ACTIONS_SETUP.md

Latest commit

 

History

History
177 lines (136 loc) · 4.55 KB

GITHUB_ACTIONS_SETUP.md

File metadata and controls

177 lines (136 loc) · 4.55 KB
Raw

GitHub Actions Setup for NPM Publishing

This document provides a complete overview of the GitHub Actions setup for automated npm publishing.

🎯 What's Been Added

1. GitHub Workflows

.github/workflows/publish.yml

  • Trigger: When a GitHub release is published
  • Purpose: Automated npm publishing
  • Features:
    • Tests on multiple Node.js versions (16, 18, 20)
    • Version consistency check between git tag and package.json
    • Automated npm publish after successful tests

.github/workflows/ci.yml

  • Trigger: Pull requests and pushes to main/master
  • Purpose: Continuous integration
  • Features:
    • Multi-version Node.js testing
    • Linting and formatting checks
    • Code coverage reporting

2. Package Configuration

Updated package.json

  • Enhanced description and metadata
  • Proper repository configuration
  • Comprehensive keywords for discoverability
  • File inclusion/exclusion for npm package
  • Node.js version requirements

.npmignore

  • Excludes development files from npm package
  • Keeps only essential files for end users
  • Reduces package size

3. Documentation

README.md

  • Comprehensive library documentation
  • Usage examples and API overview
  • Development and publishing instructions

PUBLISHING.md

  • Detailed publishing workflow guide
  • Setup instructions for maintainers
  • Troubleshooting guide

CHANGELOG.md

  • Version history tracking
  • Follows Keep a Changelog format
  • Ready for automated updates

🚀 How to Use

For First-Time Setup

  1. Create NPM Account

    # Visit https://www.npmjs.com/ and create account

  2. Generate NPM Token

    # Go to https://www.npmjs.com/settings/tokens
# Create "Automation" token

  3. Add GitHub Secret

    # Repository Settings → Secrets → Actions
# Add secret: NPM_TOKEN = your_npm_token

For Publishing a Release

  1. Update Version

    npm version patch  # or minor/major
git push

  2. Create GitHub Release

    • Go to GitHub repository
    • Releases → Create new release
    • Tag: v1.0.1 (matching package.json)
    • Publish release

  3. Automatic Publishing

    • GitHub Action runs automatically
    • Tests pass → Package published to npm
    • Monitor in Actions tab

🔧 Workflow Details

Publish Workflow Steps

  1. Multi-Version Testing

    • Runs tests on Node.js 16, 18, 20
    • Ensures compatibility across versions

  2. Version Validation

    • Checks git tag matches package.json version
    • Prevents version mismatches

  3. Build & Publish

    • Builds TypeScript to JavaScript
    • Publishes to npm registry

CI Workflow Steps

  1. Code Quality

    • ESLint for code quality
    • Prettier for formatting
    • TypeScript compilation

  2. Testing

    • Unit tests with AVA
    • Coverage reporting
    • Multi-Node.js version support

📦 Package Structure

ream.js/
├── .github/workflows/     # GitHub Actions
├── build/                 # Compiled output (published)
├── src/                   # Source code (not published)
├── package.json          # Package configuration
├── .npmignore            # NPM exclusions
├── README.md             # Main documentation
├── CHANGELOG.md          # Version history
└── PUBLISHING.md         # Publishing guide

🛡️ Security & Best Practices

NPM Token Security

  • Use "Automation" tokens for CI/CD
  • Store as GitHub repository secret
  • Never commit tokens to code

Version Management

  • Follow semantic versioning
  • Update CHANGELOG.md for each release
  • Test thoroughly before releasing

Quality Gates

  • All tests must pass before publishing
  • Code quality checks enforced
  • Multi-Node.js version compatibility

🔍 Monitoring & Troubleshooting

Check Workflow Status

  • GitHub repository → Actions tab
  • View logs for failed runs
  • Monitor npm package page

Common Issues

  1. Version Mismatch: Ensure git tag matches package.json
  2. Test Failures: Fix tests before creating release
  3. NPM Token: Verify secret is set correctly
  4. Package Name: Ensure unique name on npm

🎉 Benefits

✅ Automated Publishing: No manual npm publish commands ✅ Quality Assurance: Tests run before every publish ✅ Version Safety: Prevents version mismatches ✅ Multi-Platform: Tests on multiple Node.js versions ✅ Documentation: Comprehensive guides for maintainers ✅ Security: Secure token management via GitHub secrets

The setup is now complete and ready for automated npm publishing! 🚀