v2.1.5

Fixed

• 🛡️ EPERM Error After sudo Install: Fixed "EPERM: operation not permitted" error when running nport after global install with sudo npm i -g nport
  • When the binary is downloaded as root, it's owned by root:root and non-root users cannot chmod it on subsequent runs
  • setExecutablePermissions() now checks if the file is already executable (fs.accessSync X_OK) before attempting chmod
  • If chmod fails with EPERM/EACCES on a non-executable file, a user-friendly warning is shown instead of crashing
  • Users who installed with sudo can now run nport normally without manual chmod

Technical Details

• setExecutablePermissions() logic:
  1. Try fs.accessSync(path, X_OK) — if it succeeds, the file is already executable; return immediately (no chmod)
  2. Try fs.chmodSync(path, '755') — if it succeeds, done
  3. If chmod fails with EPERM/EACCES, log a warning but don't crash; the binary was installed with sudo and should still be functional

Migration

• No action needed — existing installs are unaffected
• Users who hit the EPERM error on v2.1.4 can simply upgrade; the fix is applied on first run

Changed

• Defense-in-depth updated: Permission checks are now 5 layers:
  1. Postinstall: downloads binary and sets chmod 755 (as installing user or root)
  2. ensureCloudflared(): calls setExecutablePermissions() on every startup
  3. setExecutablePermissions(): skips chmod if already executable; warns but doesn't crash on EPERM
  4. BinaryManager.validate(): checks X_OK access, auto-fixes with chmod
  5. BinaryManager.handleError(): shows troubleshooting tips + cleans up tunnel

v2.1.4

[2.1.4] - 2026-03-16

Fixed

• 🐧 Linux EACCES Spawn Error: Fixed "spawn cloudflared EACCES" permission denied error on Linux
  • Binary now always has execute permissions verified and auto-repaired before spawning
  • ensureCloudflared() is called on every run, not just when the binary is missing
  • BinaryManager.validate() now checks execute permissions (X_OK), not just file existence
  • Auto-fixes permissions with chmod 755 if the binary exists but isn't executable
  • Shows clear manual fix command (chmod +x <path>) if auto-repair fails
• 🔧 Postinstall Binary Download: Fixed binary not being downloaded during npm install
  • Postinstall script now explicitly calls ensureCloudflared() instead of relying on module-level guard that didn't trigger during install
  • Errors during postinstall are now logged as warnings instead of being silently swallowed
  • Users are informed the binary will be downloaded on first run if postinstall fails

Improved

• 🧹 Orphaned Tunnel Cleanup: Spawn failures now trigger automatic tunnel cleanup
  • Previously, if cloudflared failed to start after tunnel creation, the tunnel was left orphaned on the backend
  • Now calls TunnelOrchestrator.cleanup() on fatal spawn errors to delete the tunnel
• 💡 Linux/macOS Error Guidance: Added EACCES-specific troubleshooting tips
  • Detects permission denied errors on Unix systems
  • Provides actionable steps: chmod +x command and reinstall instructions
  • Matches the existing Windows-specific error guidance

Technical Details

• Defense-in-depth: Permission issues are caught at 4 layers:
  1. Postinstall: downloads binary and sets chmod 755
  2. ensureCloudflared(): runs on every startup, re-applies permissions
  3. BinaryManager.validate(): checks X_OK access, auto-fixes with chmod
  4. BinaryManager.handleError(): shows troubleshooting tips + cleans up tunnel
• BinaryManager.attachHandlers(): New onFatalError callback parameter for spawn error recovery

v2.1.3

Fixed

• 🪟 Windows Spawn Error: Fixed "spawn UNKNOWN" error on Windows
  • Added Windows-specific spawn options (windowsHide, shell, stdio)
  • Process now spawns correctly with proper path resolution on Windows
  • Added helpful troubleshooting tips for Windows users when spawn fails

Improved

• 🔧 Better Windows Error Guidance: Enhanced error messages for Windows users
  • Detects common spawn errors (UNKNOWN, ENOENT)
  • Provides actionable troubleshooting steps:
    • Check Windows Defender/antivirus blocking
    • Try running as Administrator
    • Reinstall nport if needed

v2.1.2

[2.1.2] - 2026-01-28

Fixed

• 📊 Analytics Integration: Fixed GA4 Measurement Protocol implementation
  • Created dedicated CLI analytics stream (G-JJHG4DP1K9) separate from website
  • Fixed session_id format (now uses numeric timestamp as required by GA4)
  • Fixed engagement_time_msec to use actual number instead of string
  • Added timestamp_micros for accurate event timing
  • Removed debug endpoint that was preventing events from being recorded
  • Added proper debug logging when NPORT_DEBUG=true

Changed

• 📦 Optimized Bundle Size: Switched from tsc to esbuild for significantly smaller package
  • New scripts/build.js bundles and minifies CLI into single file
  • Tree-shaking removes unused code
  • Disabled TypeScript declaration and source map generation
  • Reduced files in npm package (only postinstall.js script included)
• ⚡ Faster Development: Improved watch mode with esbuild
  • Minification disabled during development for faster rebuilds
  • Concurrent watching for main CLI and bin-manager entry points
  • Better console output showing active file monitoring

Improved

• 🧪 Enhanced Smoke Tests: Better npm package validation in CI
  • Tests now simulate full npm pack/install flow
  • Installation tested from generated tarball
  • More accurate pre-publish validation

Technical Details

• esbuild Configuration:
  • Target: Node.js 20
  • Format: ESM
  • External dependencies: axios, chalk, ora (avoids CJS/ESM issues)
  • Shebang added via esbuild banner instead of source file
• tsconfig.json: Updated with noEmit: true, esbuild handles output
• Package Size: Significantly reduced dist folder size
• Analytics Events: cli_start, tunnel_created, tunnel_error, tunnel_shutdown, update_available

v2.1.1

[2.1.1] - 2026-01-27

Fixed

• 🐛 NPM Package Build: Fixed missing dist/ folder in published package
  • Added build step to npm-publish workflow before publishing
  • Package now includes compiled JavaScript files correctly

Added

• 🚀 CI/CD Workflows: Added GitHub Actions for automated deployments
  • ci.yml: Runs tests on push to main and pull requests
  • deploy-server.yml: Auto-deploys Cloudflare Worker on server changes
  • deploy-website.yml: Auto-deploys website to Cloudflare Pages on changes
• 🧪 Server Test Configuration: Fixed Vitest config for CI environment
  • Added miniflare bindings for test environment variables
  • Tests now pass in CI without .dev.vars file
• ⚙️ Wrangler Configuration: Added preview_urls setting to suppress warnings

v2.1.0

[2.1.0] - 2026-01-27

Added

• 🔷 Full TypeScript Migration: Complete rewrite of CLI and Server in TypeScript
  • Strict type checking enabled across the entire codebase
  • All modules converted from JavaScript to TypeScript
  • Type-safe interfaces for configuration, tunnels, analytics, and i18n
  • Better IDE support with IntelliSense and autocompletion
• 📚 Comprehensive Documentation: New docs folder with detailed guides
  • docs/ARCHITECTURE.md: System overview, component diagrams, and data flow
  • docs/API.md: Complete API reference with endpoints and examples
  • docs/CONTRIBUTING.md: Contribution guidelines and development setup
• 🤖 AI Context Support: Added .ai/context.md for AI-assisted development
  • Project structure and key patterns documented
  • Coding conventions and architecture decisions
  • Makes AI pair programming more effective
• 🧪 Unit Testing with Vitest: Comprehensive test suite for CLI
  • Tests for argument parsing (tests/args.test.ts)
  • Tests for version comparison (tests/version.test.ts)
  • Tests for state management (tests/state.test.ts)
  • Easy to run with npm test
• 📋 Code Ownership: Added .github/CODEOWNERS file
  • Clear ownership for code review assignments
  • Faster PR reviews with automatic reviewer assignment
• 📝 Cursor Rules: Added .cursorrules for consistent AI assistance
  • Project-specific coding conventions
  • TypeScript and naming guidelines
  • Common patterns and anti-patterns
• 🔄 Auto-download Cloudflared: Binary downloads automatically on first run
  • No need to run separate install commands
  • Seamless first-time user experience
  • Progress indicator during download
• 🔒 Protected Subdomain Support: Enhanced error handling for reserved subdomains
  • User-friendly error message when trying to create protected subdomains (like api)
  • Formatted error output matching existing error style
  • Helpful suggestions to use alternative subdomain names
  • Prevents accidental use of backend service subdomains
• 📋 TODO Management: Added TODO.md for tracking planned features
  • Move time limit enforcement to backend
  • Update README powered-by section
  • Track terminal link clicks

Changed

• 🏗️ Project Structure: Reorganized for better maintainability
  • All source code in src/ directory
  • Type definitions in src/types/
  • Shared constants in src/constants.ts
  • Tests in tests/ directory
• 📦 Build System: Updated to TypeScript compilation
  • Uses tsc for compilation
  • Output to dist/ directory
  • Source maps for debugging
• 🔧 Development Workflow: Improved developer experience
  • npm run dev for watch mode
  • npm run build for production
  • npm test for running tests
  • npm run lint for type checking
• ⚙️ System Requirements: Updated to Node.js 20+
  • Minimum Node.js version: 20.0.0
  • Minimum npm version: 10.0.0
  • Better security and performance with latest LTS

Improved

• ✨ Better Error Messages: Enhanced user feedback for protected subdomains
  • Catches SUBDOMAIN_PROTECTED errors from backend
  • Formats error messages consistently with other error types
  • Shows actionable options when subdomain is reserved

Fixed

• 🐛 Intel Mac Binary Download: Fixed cloudflared binary download on Intel Macs
  • Node.js reports architecture as x64, not amd64 - now correctly mapped
  • Fixed ARM64 Macs to download the correct cloudflared-darwin-arm64.tgz binary
  • Previously ARM64 Macs were incorrectly downloading the AMD64 binary

v2.0.7

[2.0.7] - 2026-01-14

Added

• 🌐 Smart Network Warning System: Intelligent handling of QUIC/network connectivity issues
  • Automatic detection and filtering of QUIC protocol errors
  • User-friendly warning messages instead of scary red error spam
  • Bilingual support (English & Vietnamese)
  • Smart throttling: Shows warning only after 5 errors, max once per 30 seconds
  • Clear explanations of what's happening and how to fix it
  • Automatic reset when connection is restored
• 🔒 Protected Subdomain Support: Enhanced error handling for reserved subdomains
  • User-friendly error message when trying to create protected subdomains (like api)
  • Formatted error output matching existing error style
  • Helpful suggestions to use alternative subdomain names
  • Prevents accidental use of backend service subdomains

Improved

• 🔇 Cleaner Terminal Output: No more error spam from cloudflared
  • QUIC timeout errors are now silently tracked instead of displayed
  • Network warnings filtered: "failed to accept QUIC stream", "timeout: no recent network activity", etc.
  • Only shows meaningful warnings when there's an actual persistent issue
  • Terminal stays clean and readable during normal operation
• 📡 Better User Communication: Context-aware network issue reporting
  • Explains that QUIC failures are usually not critical
  • Tunnel continues working via HTTP/2 fallback
  • Provides actionable troubleshooting steps
  • Reassures users that the tunnel is still functional
• ✨ Better Error Messages: Enhanced user feedback for protected subdomains
  • Catches SUBDOMAIN_PROTECTED errors from backend
  • Formats error messages consistently with other error types
  • Shows actionable options when subdomain is reserved

Technical Details

• Network Error Patterns: Added detection for 7 common QUIC/network error patterns
• State Management: New network issue tracking in application state
  • networkIssueCount: Counter for network errors
  • lastNetworkWarningTime: Timestamp tracking for cooldown
  • shouldShowNetworkWarning(): Smart decision logic
• Configuration: New NETWORK_CONFIG with threshold and cooldown settings
• Bilingual Messages: Complete translations for all network warning messages
• Protected Subdomain Handling: Enhanced error handling in src/api.js
  • Added check for SUBDOMAIN_PROTECTED error type
  • Consistent formatting with existing error messages
  • Clear user guidance for alternative subdomain choices

User Experience

Before:

[Cloudflared] 2026-01-14T04:33:02Z ERR failed to accept QUIC stream...
[Cloudflared] 2026-01-14T04:33:03Z ERR failed to accept QUIC stream...
[Cloudflared] 2026-01-14T04:33:04Z ERR failed to accept QUIC stream...
[Cloudflared] 2026-01-14T04:33:05Z ERR failed to accept QUIC stream...

After:

✔ [1/2] Connection established...
✔ [2/2] Compression enabled...

⚠️  NETWORK CONNECTIVITY ISSUE DETECTED
   Cloudflared is having trouble maintaining a stable connection...
   📡 Your tunnel is still working, but connection quality may be affected.
   
   💡 Possible reasons:
      • Unstable internet connection or high packet loss
      • Firewall/Router blocking UDP traffic (QUIC protocol)
      • ISP throttling or network congestion
      
   🔧 What to try:
      • Check your internet connection stability
      • Try connecting from a different network
      • Disable VPN/Proxy if you're using one
      
   ℹ️  This is usually not critical - your tunnel should continue working normally.

v2.0.6

NPort v2.0.6 Release Summary

🎉 Release Date: January 13, 2026

---

🚀 Major Features

1. Backend URL Configuration

Full control over which backend server to use

# Save backend permanently
nport --set-backend https://api.nport.link

# Use backend temporarily
nport 3000 -b https://your-backend.com

# Use environment variable
export NPORT_BACKEND_URL=https://api.nport.link
nport 3000

Priority System:

1. CLI flag (--backend / -b) - Highest
2. Saved config (--set-backend)
3. Environment variable (NPORT_BACKEND_URL)
4. Default (https://api.nport.link) - Lowest

2. Unified Configuration System

All settings in one place

Before (v2.0.5):

• Language: ~/.nport/lang (plain text file)
• No backend configuration

After (v2.0.6):

• Everything: ~/.nport/config.json (structured JSON)
• Easy to read and edit
• Consistent approach

Example config file:

{
  "backendUrl": "https://api.nport.link",
  "language": "en"
}

3. New Default Backend

Updated from nport.tuanngocptn.workers.dev to api.nport.link

Benefits:

• ✓ Professional domain structure
• ✓ Better branding with main domain
• ✓ Shorter and easier to remember
• ✓ Clearer purpose (api subdomain)

---

📝 Changes Summary

Added

• --backend <url> / -b <url> - Temporary backend override
• --set-backend <url> - Save backend URL permanently
• NPORT_BACKEND_URL environment variable support
• Unified configuration manager (src/config-manager.js)
• Automatic migration from v2.0.5 format

Changed

• Default backend URL: api.nport.link
• Language storage: Now in config.json instead of separate file
• Configuration approach: Unified system for all settings

Improved

• Code organization with centralized config management
• Consistency across all configuration options
• Better documentation with comprehensive examples

---

🔄 Migration

Automatic Migration from v2.0.5

When you upgrade to v2.0.6, the following happens automatically:

1. Old language file (~/.nport/lang) → New config (~/.nport/config.json)
2. Old file deleted after successful migration
3. No manual steps required

Example migration:

Before (v2.0.5):

~/.nport/lang
--------------
vi

After (v2.0.6):

~/.nport/config.json
--------------------
{
  "language": "vi"
}

---

💡 Usage Examples

Basic Usage (No changes needed!)

# Works exactly the same as before
nport 3000
nport 3000 -s myapp

New: Set Backend Once

# Set it once
nport --set-backend https://api.nport.link

# Use forever
nport 3000
nport 3000 -s api
nport 8080 -s webhooks

New: Multiple Environments

# Development
nport --set-backend http://localhost:8787
nport 3000

# Switch to production
nport --set-backend https://api.nport.link
nport 3000

New: Team Configuration

# Everyone on team runs once
nport --set-backend https://company-backend.example.com

# Then everyone uses nport normally
nport 3000

---

🎯 Upgrade Instructions

NPM (Recommended)

npm install -g nport@latest

Verify Version

nport -v
# Should show: NPort v2.0.6

Test New Features

# 1. Set backend
nport --set-backend https://api.nport.link

# 2. Check config
cat ~/.nport/config.json

# 3. Use normally
nport 3000

---

✅ Backward Compatibility

100% backward compatible!

• ✓ All v2.0.5 commands work exactly the same
• ✓ Automatic configuration migration
• ✓ No breaking changes
• ✓ If you don't use new features, nothing changes

---

📚 Documentation

Updated Files

• ✅ README.md - Main documentation with backend options
• ✅ CLIENT_SETUP.md - Simplified setup guide
• ✅ CHANGELOG.md - Complete changelog
• ✅ All configuration examples updated

New Documentation Topics

• Backend URL configuration
• Persistent configuration
• Priority system
• Multiple environment setup
• Team configuration

---

🐛 Bug Fixes

No bugs fixed in this release (feature release only).

---

🔮 What's Next

Potential future features (not committed):

• More language options
• Additional configuration settings
• Extended timeout options
• Custom analytics preferences

---

💬 Feedback

We'd love to hear your thoughts on v2.0.6!

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• ⭐ Star on GitHub: tuanngocptn/nport
• ☕ Support Development: Buy Me a Coffee

---

🙏 Credits

Developed by: Nick Pham

Contributors:

• Backend URL feature implementation
• Unified configuration system
• Documentation improvements
• Testing and feedback

---

Made with ❤️ in Vietnam

Thank you for using NPort! 🚀

v2.0.5

Full Changelog: v2.0.4...v2.0.5

v2.0.4

Full Changelog: v2.0.3...v2.0.4