Publishing VibeTunnel to npm

This guide helps the repository owner publish VibeTunnel to npm as a standalone package.

Prerequisites

npm account with publish access to vibetunnel
Node.js 22.12 through 24.x installed
Apple Silicon Mac for the complete multi-platform package
Docker installed (for Linux builds)
Rustup installed; native/vt-fwd/rust-toolchain.toml pins the forwarder toolchain

Publishing Checklist

1. Update Version

# Update version in both package files
cd web/
# Edit version in package.json and package.npm.json
vim package.json package.npm.json

2. Build for npm

# Clean and build for all platforms on macOS
pnpm run clean
PACKAGE_TARBALL="./vibetunnel-$(node -p "require('./package.json').version").tgz"
rm -f "$PACKAGE_TARBALL"
pnpm run build:npm
test -f "$PACKAGE_TARBALL"

# This creates dist-npm/ and vibetunnel-<version>.tgz with:
# - Compiled JavaScript (lib/)
# - Static files (public/)
# - Native-module prebuilds (prebuilds/)
# - Rust forwarders (forwarders/<platform>-<arch>/vibetunnel-fwd)
# - Package.json ready for publishing

3. Test Locally

# build:npm runs npm pack in dist-npm/ and moves the archive here, to web/
pnpm run test:npm-package "$PACKAGE_TARBALL"
npm install -g "$PACKAGE_TARBALL"

# Test basic functionality
vibetunnel --version
vibetunnel --help
vibetunnel --no-auth  # Test server starts

# Test with ngrok
vibetunnel --no-auth --ngrok

# Cleanup
npm uninstall -g vibetunnel

4. Publish to npm

# Login to npm (first time only)
npm login
# Username: [your-username]
# Password: [your-password]  
# Email: [your-email]
# OTP: [if 2FA enabled]

# Publish the exact archive tested above. Use one command, matching the version:
npm publish "$PACKAGE_TARBALL" --tag beta    # prerelease, e.g. 1.0.0-beta.18
npm publish "$PACKAGE_TARBALL" --tag latest  # stable, e.g. 1.0.0

5. Verify Publication

# Check it's published
npm view vibetunnel

# Test installation
npx vibetunnel --version

# Test in a fresh directory
cd /tmp
npx vibetunnel --no-auth

Package Configuration

The package is configured with:

Name: vibetunnel (unscoped)
Main: lib/cli.js (entry point)
Bin: vibetunnel command
Platforms: macOS (x64, arm64) and Linux (x64, arm64)
Node: Requires Node.js 22+

Rust Forwarder Outputs

pnpm run build builds the host forwarder and installs it at native/vibetunnel-fwd and bin/vibetunnel-fwd under web/. pnpm run build:npm additionally stages the selected package targets at:

web/forwarders/darwin-arm64/vibetunnel-fwd
web/forwarders/darwin-x64/vibetunnel-fwd
web/forwarders/linux-arm64/vibetunnel-fwd
web/forwarders/linux-x64/vibetunnel-fwd

The selected directories are copied unchanged to web/dist-npm/forwarders/ and then into the package archive. At runtime the CLI selects forwarders/<process.platform>-<process.arch>/vibetunnel-fwd; the postinstall script makes that binary executable. A complete macOS build creates all four targets. Filtered and --current-only builds include only their selected targets.

What Gets Published

The npm package includes:

✅ Compiled JavaScript (lib/)
✅ Web UI files (public/)
✅ CLI binary (bin/vibetunnel)
✅ Rust forwarders (forwarders/<platform>-<arch>/vibetunnel-fwd)
✅ Prebuilt native binaries (prebuilds/)
✅ README files (README.md, README.npm.md, README.standalone.md)
✅ Runtime-only Dockerfile for building directly from extracted package contents
✅ Postinstall scripts

Not included:

❌ Source TypeScript files
❌ Test files
❌ Development configs
❌ Mac/iOS app code

Version Management

Follow semantic versioning:

Patch (1.0.x): Bug fixes, small improvements
Minor (1.x.0): New features, backward compatible
Major (x.0.0): Breaking changes

Current version scheme:

1.0.0-beta.X for beta releases
1.0.0 for first stable release

Troubleshooting

Build Fails

# Clean everything and retry
pnpm run clean
rm -rf dist-npm/
pnpm install
pnpm run build:npm

Complete multi-platform builds require macOS. On Linux, use pnpm run build:npm -- --current-only or pnpm run build:npm -- --platform linux.

Missing Prebuilds

# Build for specific platform
pnpm run build:npm -- --platform darwin --arch arm64

Permission Denied

# Ensure you're logged in with correct account
npm whoami
npm access ls-packages

# If using npm org teams, ensure team access for the package

Already Published Version

# Bump version first
npm version patch  # or minor/major
# Then rebuild and republish

Post-Publishing

After successful publication:

Test with npx: npx vibetunnel --version
Update documentation: Add npm badge to main README
Create GitHub release: Tag the version
Announce: Twitter, Discord, etc.

Automation (Future)

Consider setting up GitHub Actions:

# .github/workflows/npm-publish.yml
name: Publish to npm
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
      - run: cd web && pnpm install
      - run: cd web && pnpm run build:npm
      - run: cd web && npm publish ./vibetunnel-*.tgz
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

Support

For issues with publishing, check:

Getting Started

Installation

Architecture

Advanced Features

Development

macOS Development

iOS Development

iOS Testing

Web Development

Release & Deployment

Tools & Integration

Maintenance

PUBLISHING

Publishing VibeTunnel to npm

Prerequisites

Publishing Checklist

1. Update Version

2. Build for npm

3. Test Locally

4. Publish to npm

5. Verify Publication

Package Configuration

Rust Forwarder Outputs

What Gets Published

Version Management

Troubleshooting

Build Fails

Missing Prebuilds

Permission Denied

Already Published Version

Post-Publishing

Automation (Future)

Support

​Publishing VibeTunnel to npm

​Prerequisites

​Publishing Checklist

​1. Update Version

​2. Build for npm

​3. Test Locally

​4. Publish to npm

​5. Verify Publication

​Package Configuration

​Rust Forwarder Outputs

​What Gets Published

​Version Management

​Troubleshooting

​Build Fails

​Missing Prebuilds

​Permission Denied

​Already Published Version

​Post-Publishing

​Automation (Future)

​Support

Publishing VibeTunnel to npm

Prerequisites

Publishing Checklist

1. Update Version

2. Build for npm

3. Test Locally

4. Publish to npm

5. Verify Publication

Package Configuration

Rust Forwarder Outputs

What Gets Published

Version Management

Troubleshooting

Build Fails

Missing Prebuilds

Permission Denied

Already Published Version

Post-Publishing

Automation (Future)

Support