linkforty/PUBLISHING.md

Publishing Guide for @linkforty/core

This guide walks you through publishing the @linkforty/core package to GitHub and npm.

Pre-Publishing Checklist

• Git repository initialized
• .gitignore configured
• .npmignore configured
• README.md complete with examples
• LICENSE file (MIT)
• CHANGELOG.md created
• CONTRIBUTING.md created
• Package builds successfully
• Examples directory with working code
• All exports properly configured in package.json

Step 1: Create GitHub Repository

Option A: Using GitHub CLI (gh)

# Install GitHub CLI if needed
brew install gh

# Login to GitHub
gh auth login

# Create repository
cd /Users/brandon/WebstormProjects/linkforty-core
gh repo create linkforty/core --public --description "Open-source deeplink management engine with device detection and analytics"

# Add remote
git remote add origin https://github.com/linkforty/core.git

Option B: Using GitHub Web UI

1. Go to https://github.com/new
2. Repository name: core
3. Organization: linkforty (or create organization first at https://github.com/organizations/new)
4. Description: "Open-source deeplink management engine with device detection and analytics"
5. Public repository
6. Do NOT initialize with README, .gitignore, or license (we have these)
7. Click "Create repository"

Then add the remote:

cd /Users/brandon/WebstormProjects/linkforty-core
git remote add origin https://github.com/linkforty/core.git

Step 2: Initial Commit and Push

cd /Users/brandon/WebstormProjects/linkforty-core

# Stage all files
git add .

# Create initial commit
git commit -m "feat: initial release of @linkforty/core v1.0.0

- Smart link routing with device detection
- Click analytics with geolocation
- UTM parameter support
- Link expiration and targeting rules
- Redis caching for performance
- PostgreSQL storage
- Full TypeScript support
- Docker deployment examples"

# Create main branch and push
git branch -M main
git push -u origin main

# Create v1.0.0 tag
git tag -a v1.0.0 -m "Release v1.0.0 - Initial public release"
git push origin v1.0.0

Step 3: Configure GitHub Repository Settings

Enable GitHub Pages (optional - for documentation)

1. Go to repository Settings → Pages
2. Source: Deploy from branch → main → /docs (if you add docs later)

Set up branch protection

1. Settings → Branches → Add rule
2. Branch name pattern: main
3. Enable:
   • Require pull request reviews before merging
   • Require status checks to pass before merging

Add repository topics

1. Go to repository main page
2. Click ⚙️ next to "About"
3. Add topics: deeplink, onelink, url-shortener, analytics, mobile-links, typescript, fastify, nodejs

Step 4: Publish to npm

Verify package contents

Before publishing, verify what will be included:

cd /Users/brandon/WebstormProjects/linkforty-core
npm pack --dry-run

This should show:

• dist/ directory (compiled JavaScript)
• *.d.ts files (TypeScript declarations)
• README.md
• LICENSE
• CHANGELOG.md
• package.json

Login to npm

npm login
# Follow prompts to enter credentials

Publish to npm

# For first-time publish of scoped package
npm publish --access public

# Verify it's published
npm view @linkforty/core

Future Updates

For subsequent releases:

# Update version in package.json
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

# This creates a git commit and tag automatically

# Push changes and tags
git push && git push --tags

# Publish to npm
npm publish

Step 5: Create GitHub Release

Using GitHub CLI

gh release create v1.0.0 \
  --title "v1.0.0 - Initial Release" \
  --notes "$(cat CHANGELOG.md | sed -n '/## \[1.0.0\]/,/^---/p' | sed '1d;$d')"

Using GitHub Web UI

1. Go to https://github.com/linkforty/core/releases/new
2. Tag: v1.0.0
3. Title: "v1.0.0 - Initial Release"
4. Description: Copy content from CHANGELOG.md for v1.0.0
5. Click "Publish release"

Step 6: Verify Publication

Check npm

# View package info
npm view @linkforty/core

# Test installation
mkdir /tmp/test-linkforty
cd /tmp/test-linkforty
npm init -y
npm install @linkforty/core

# Verify it works
node -e "const { createServer } = require('@linkforty/core'); console.log('✓ Package works!');"

Check GitHub

• Visit https://github.com/linkforty/core
• Verify README displays correctly
• Check releases page
• Verify topics are visible

Step 7: Post-Publication Tasks

Update badges in README (if needed)

The npm version badge should now work:

[![npm version](https://img.shields.io/npm/v/@linkforty/core.svg)](https://www.npmjs.com/package/@linkforty/core)

Set up GitHub Actions (optional)

Create .github/workflows/publish.yml for automated publishing:

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Announce the release

• Post on social media (Twitter, LinkedIn, Reddit r/opensource)
• Submit to https://news.ycombinator.com
• Share in relevant Discord/Slack communities
• Update your portfolio/website

Marketing Checklist

After publication, promote your open-source project:

• Share on Twitter/X with relevant hashtags (#opensource #nodejs #typescript)
• Post on LinkedIn
• Submit to https://www.producthunt.com
• Share on Reddit: r/opensource, r/node, r/typescript
• Post on Hacker News: https://news.ycombinator.com/submit
• Add to awesome lists (search "awesome-nodejs" on GitHub)
• Write a blog post about the project
• Create demo video/GIF for README
• Set up project website (optional)

Maintenance

Responding to Issues

• Enable GitHub Discussions for questions
• Use issue templates for bug reports and feature requests
• Triage issues weekly
• Label issues appropriately

Accepting Contributions

1. Review PRs promptly
2. Require tests for new features
3. Maintain code quality standards
4. Update CHANGELOG.md for each release
5. Credit contributors in release notes

Release Schedule

Suggested release cadence:

• Patch releases (bug fixes): As needed
• Minor releases (new features): Monthly or quarterly
• Major releases (breaking changes): Annually or as needed

Support

If you encounter any issues during publication:

1. Verify npm credentials: npm whoami
2. Check package name availability: npm view @linkforty/core
3. Ensure you have permissions for the @linkforty scope
4. Review npm documentation: https://docs.npmjs.com/

For GitHub issues:

• Check SSH keys: ssh -T git@github.com
• Verify remote: git remote -v
• Check permissions: Ensure you own the repository or have write access

---

Ready to publish? Follow these steps in order and you'll have your package live on npm and GitHub! 🚀