nport 2.0.5 → 2.0.6

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to NPort will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.6] - 2026-01-13
+
+### Added
+- 🔧 **Backend URL Configuration**: Full control over backend server
+  - `--backend` / `-b` flag for temporary backend override
+  - `--set-backend` command to save backend URL permanently
+  - `NPORT_BACKEND_URL` environment variable support
+  - Saved backend configuration persists across sessions
+  - Priority system: CLI flag > Saved config > Env var > Default
+- 🗂️ **Unified Configuration System**: All settings in one place
+  - New centralized `config-manager.js` module
+  - All preferences stored in `~/.nport/config.json`
+  - Automatic migration from old format (v2.0.5)
+  - Easy to read and manually edit JSON format
+- 🌐 **New Default Backend**: Updated to `api.nport.link`
+  - Professional domain structure
+  - Better branding alignment
+  - Shorter and easier to remember
+
+### Changed
+- 📝 **Language Configuration**: Now uses unified config system
+  - Language setting moved from `~/.nport/lang` to `~/.nport/config.json`
+  - Automatic migration from old file format
+  - Consistent configuration approach across all settings
+- 📚 **Documentation Updates**: Complete overhaul
+  - Updated `README.md` with backend configuration options
+  - New `CLIENT_SETUP.md` focused on npm installation and backend setup
+  - Comprehensive backend URL documentation
+  - Clear priority order explanation
+
+### Improved
+- 🎯 **Consistency**: Unified approach to all configuration
+  - Backend URL and language now use same storage system
+  - Single config file for all preferences
+  - Cleaner architecture and code organization
+- 💾 **Configuration File Structure**:
+  ```json
+  {
+    "backendUrl": "https://api.nport.link",
+    "language": "en"
+  }
+  ```
+
+### Migration
+- Automatic migration from v2.0.5 configuration files
+- Old `~/.nport/lang` file automatically migrated to `config.json`
+- No manual steps required
+- Old files removed after successful migration
+
 ## [2.0.5] - 2026-01-13
 
 ### Added
@@ -61,6 +110,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version Upgrade Guide
 
+### From 2.0.5 to 2.0.6
+
+```bash
+npm install -g nport@latest
+```
+
+**New Features to Try:**
+
+1. **Set Your Backend Permanently**
+   ```bash
+   nport --set-backend https://api.nport.link
+   ```
+
+2. **Use Custom Backend Temporarily**
+   ```bash
+   nport 3000 -b https://your-backend.com
+   ```
+
+3. **Check Current Configuration**
+   ```bash
+   cat ~/.nport/config.json
+   ```
+
+4. **Use Environment Variable**
+   ```bash
+   export NPORT_BACKEND_URL=https://your-backend.com
+   nport 3000
+   ```
+
+**Breaking Changes:** None - fully backward compatible!
+
+**Migration:** Your language preference from v2.0.5 will be automatically migrated to the new unified config format.
+
 ### From 2.0.4 to 2.0.5
 
 ```bash

package/README.md

@@ -158,6 +158,8 @@ nport <port> [options]
 |--------|-------|-------------|---------|
 | `<port>` | - | Local port to tunnel (default: 8080) | `nport 3000` |
 | `--subdomain` | `-s` | Custom subdomain | `nport 3000 -s myapp` |
+| `--backend` | `-b` | Custom backend URL (temporary) | `nport 3000 -b https://your-backend.com` |
+| `--set-backend` | - | Save backend URL permanently | `nport --set-backend https://your-backend.com` |
 | `--language` | `-l` | Set language (en/vi) or prompt | `nport 3000 -l vi` |
 | `--version` | `-v` | Show version information | `nport -v` |
 
@@ -177,6 +179,61 @@ nport -l                    # Interactive prompt
 
 On first run or when using `--language` without a value, you'll see an interactive language picker. Your choice is automatically saved for future sessions.
 
+### Backend URL Options
+
+NPort uses a default backend at `https://api.nport.link`, but you can use your own backend server.
+
+#### Temporary Backend (One-time Use)
+
+Use a custom backend for just the current session:
+
+```bash
+# Use custom backend via CLI flag
+nport 3000 --backend https://your-backend.com
+nport 3000 -b https://your-backend.com
+
+# Use custom backend via environment variable
+export NPORT_BACKEND_URL=https://your-backend.com
+nport 3000
+
+# Combine with other options
+nport 3000 -s myapp -b https://your-backend.com
+```
+
+#### Persistent Backend (Saved Configuration)
+
+Save a backend URL to use automatically in all future sessions:
+
+```bash
+# Save backend URL permanently
+nport --set-backend https://your-backend.com
+
+# Now all future commands will use this backend
+nport 3000              # Uses saved backend
+nport 3000 -s myapp     # Uses saved backend
+
+# Clear saved backend (return to default)
+nport --set-backend
+
+# Override saved backend temporarily
+nport 3000 -b https://different-backend.com
+```
+
+**Configuration Priority:**
+1. CLI flag (`--backend` or `-b`) - Highest priority
+2. Saved config (`--set-backend`)
+3. Environment variable (`NPORT_BACKEND_URL`)
+4. Default (`https://api.nport.link`) - Lowest priority
+
+**Configuration Storage:**
+Your backend preference is saved in `~/.nport/config.json`
+
+This is useful if you want to:
+- **Self-host**: Run your own NPort backend (see [server/](server/) directory)
+- **Development**: Test against a local backend
+- **Custom domains**: Use your own domain for tunnel URLs
+- **Enterprise**: Use a company-hosted backend server
+
 ### Version Information
 
 ```bash

package/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
 import ora from "ora";
+import chalk from "chalk";
 import { ArgumentParser } from "./src/args.js";
 import { TunnelOrchestrator } from "./src/tunnel.js";
 import { VersionManager } from "./src/version.js";
 import { UI } from "./src/ui.js";
 import { CONFIG } from "./src/config.js";
 import { lang } from "./src/lang.js";
+import { configManager } from "./src/config-manager.js";
 
 /**
  * NPort - Free & Open Source ngrok Alternative
@@ -26,6 +28,32 @@ async function displayVersion() {
   UI.displayVersion(CONFIG.CURRENT_VERSION, updateInfo);
 }
 
+/**
+ * Handle --set-backend command
+ */
+function handleSetBackend(value) {
+  if (value === 'clear') {
+    // Clear saved backend URL
+    configManager.setBackendUrl(null);
+    console.log(chalk.green('✔ Backend URL cleared. Using default backend.'));
+    console.log(chalk.gray('  Default: https://api.nport.link\n'));
+  } else {
+    // Save new backend URL
+    configManager.setBackendUrl(value);
+    console.log(chalk.green('✔ Backend URL saved successfully!'));
+    console.log(chalk.cyan(`  Backend: ${value}`));
+    console.log(chalk.gray('\n  This backend will be used for all future sessions.'));
+    console.log(chalk.gray('  To clear: nport --set-backend\n'));
+  }
+  
+  // Show current configuration
+  const savedUrl = configManager.getBackendUrl();
+  if (savedUrl) {
+    console.log(chalk.white('Current configuration:'));
+    console.log(chalk.cyan(`  Saved backend: ${savedUrl}`));
+  }
+}
+
 /**
  * Main application entry point
  */
@@ -45,6 +73,12 @@ async function main() {
       process.exit(0);
     }
     
+    // Handle --set-backend command
+    if (config.setBackend) {
+      handleSetBackend(config.setBackend);
+      process.exit(0);
+    }
+    
     // If only --language flag was used, show success message and exit
     if (config.language === 'prompt' && 
         (args.includes('--language') || args.includes('--lang') || args.includes('-l'))) {
@@ -52,6 +86,14 @@ async function main() {
       process.exit(0);
     }
     
+    // Load saved backend URL if no CLI backend specified
+    if (!config.backendUrl) {
+      const savedBackend = configManager.getBackendUrl();
+      if (savedBackend) {
+        config.backendUrl = savedBackend;
+      }
+    }
+    
     // Start tunnel
     await TunnelOrchestrator.start(config);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nport",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Free & open source ngrok alternative - Tunnel HTTP/HTTPS connections via Cloudflare Edge with custom subdomains",
   "type": "module",
   "main": "index.js",

package/src/api.js

@@ -8,9 +8,10 @@ import { state } from "./state.js";
  * Handles communication with the NPort backend service
  */
 export class APIClient {
-  static async createTunnel(subdomain) {
+  static async createTunnel(subdomain, backendUrl = null) {
+    const url = backendUrl || CONFIG.BACKEND_URL;
     try {
-      const { data } = await axios.post(CONFIG.BACKEND_URL, { subdomain });
+      const { data } = await axios.post(url, { subdomain });
 
       if (!data.success) {
         throw new Error(data.error || "Unknown error from backend");
@@ -26,8 +27,9 @@ export class APIClient {
     }
   }
 
-  static async deleteTunnel(subdomain, tunnelId) {
-    await axios.delete(CONFIG.BACKEND_URL, {
+  static async deleteTunnel(subdomain, tunnelId, backendUrl = null) {
+    const url = backendUrl || CONFIG.BACKEND_URL;
+    await axios.delete(url, {
       data: { subdomain, tunnelId },
     });
   }

package/src/args.js

@@ -2,14 +2,16 @@ import { CONFIG } from "./config.js";
 
 /**
  * Command Line Argument Parser
- * Handles parsing of CLI arguments for port, subdomain, and language
+ * Handles parsing of CLI arguments for port, subdomain, language, and backend URL
  */
 export class ArgumentParser {
   static parse(argv) {
     const port = this.parsePort(argv);
     const subdomain = this.parseSubdomain(argv);
     const language = this.parseLanguage(argv);
-    return { port, subdomain, language };
+    const backendUrl = this.parseBackendUrl(argv);
+    const setBackend = this.parseSetBackend(argv);
+    return { port, subdomain, language, backendUrl, setBackend };
   }
 
   static parsePort(argv) {
@@ -66,6 +68,43 @@ export class ArgumentParser {
     return null; // No language specified
   }
 
+  static parseBackendUrl(argv) {
+    // Try backend URL flag formats: --backend=url, --backend url, -b url
+    const formats = [
+      () => this.findFlagWithEquals(argv, "--backend="),
+      () => this.findFlagWithEquals(argv, "-b="),
+      () => this.findFlagWithValue(argv, "--backend"),
+      () => this.findFlagWithValue(argv, "-b"),
+    ];
+
+    for (const format of formats) {
+      const url = format();
+      if (url) return url;
+    }
+
+    return null; // No backend URL specified
+  }
+
+  static parseSetBackend(argv) {
+    // Try set-backend flag formats: --set-backend=url, --set-backend url
+    const formats = [
+      () => this.findFlagWithEquals(argv, "--set-backend="),
+      () => this.findFlagWithValue(argv, "--set-backend"),
+    ];
+
+    for (const format of formats) {
+      const url = format();
+      if (url) return url;
+    }
+
+    // Check if --set-backend flag exists without value (to clear)
+    if (argv.includes('--set-backend')) {
+      return 'clear';
+    }
+
+    return null; // No set-backend specified
+  }
+
   static findFlagWithEquals(argv, flag) {
     const arg = argv.find((a) => a.startsWith(flag));
     return arg ? arg.split("=")[1] : null;

package/src/config-manager.js

@@ -0,0 +1,139 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+/**
+ * Configuration Manager
+ * Handles persistent storage of user preferences (backend URL, language, etc.)
+ */
+class ConfigManager {
+  constructor() {
+    this.configDir = path.join(os.homedir(), ".nport");
+    this.configFile = path.join(this.configDir, "config.json");
+    this.oldLangFile = path.join(this.configDir, "lang"); // For migration
+    this.config = this.loadConfig();
+    this.migrateOldConfig();
+  }
+
+  /**
+   * Load configuration from file
+   * @returns {object} Configuration object
+   */
+  loadConfig() {
+    try {
+      if (fs.existsSync(this.configFile)) {
+        const data = fs.readFileSync(this.configFile, "utf8");
+        return JSON.parse(data);
+      }
+    } catch (error) {
+      // If config is corrupted or invalid, return default
+      console.warn("Warning: Could not load config file, using defaults");
+    }
+    return {};
+  }
+
+  /**
+   * Migrate old configuration files to new unified format from version 2.0.5
+   */
+  migrateOldConfig() {
+    try {
+      // Migrate old language file if it exists and no language in config
+      if (!this.config.language && fs.existsSync(this.oldLangFile)) {
+        const oldLang = fs.readFileSync(this.oldLangFile, "utf8").trim();
+        if (oldLang && ["en", "vi"].includes(oldLang)) {
+          this.config.language = oldLang;
+          this.saveConfig();
+          // Optionally delete old file
+          try {
+            fs.unlinkSync(this.oldLangFile);
+          } catch (err) {
+            // Ignore if can't delete
+          }
+        }
+      }
+    } catch (error) {
+      // Ignore migration errors
+    }
+  }
+
+  /**
+   * Save configuration to file
+   */
+  saveConfig() {
+    try {
+      // Ensure .nport directory exists
+      if (!fs.existsSync(this.configDir)) {
+        fs.mkdirSync(this.configDir, { recursive: true });
+      }
+      fs.writeFileSync(this.configFile, JSON.stringify(this.config, null, 2), "utf8");
+      return true;
+    } catch (error) {
+      console.warn("Warning: Could not save configuration");
+      return false;
+    }
+  }
+
+  /**
+   * Get backend URL from config
+   * @returns {string|null} Saved backend URL or null
+   */
+  getBackendUrl() {
+    return this.config.backendUrl || null;
+  }
+
+  /**
+   * Set backend URL in config
+   * @param {string} url - Backend URL to save
+   * @returns {boolean} Success status
+   */
+  setBackendUrl(url) {
+    if (!url) {
+      delete this.config.backendUrl;
+    } else {
+      this.config.backendUrl = url;
+    }
+    return this.saveConfig();
+  }
+
+  /**
+   * Get language from config
+   * @returns {string|null} Saved language code or null
+   */
+  getLanguage() {
+    return this.config.language || null;
+  }
+
+  /**
+   * Set language in config
+   * @param {string} lang - Language code to save (e.g., 'en', 'vi')
+   * @returns {boolean} Success status
+   */
+  setLanguage(lang) {
+    if (!lang) {
+      delete this.config.language;
+    } else {
+      this.config.language = lang;
+    }
+    return this.saveConfig();
+  }
+
+  /**
+   * Get all configuration
+   * @returns {object} All configuration
+   */
+  getAll() {
+    return { ...this.config };
+  }
+
+  /**
+   * Clear all configuration
+   * @returns {boolean} Success status
+   */
+  clear() {
+    this.config = {};
+    return this.saveConfig();
+  }
+}
+
+// Export singleton instance
+export const configManager = new ConfigManager();

package/src/config.js

@@ -7,11 +7,23 @@ const __dirname = path.dirname(path.dirname(__filename));
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 
+// Helper function to get backend URL with priority order
+function getBackendUrl() {
+  // Priority 1: Environment variable
+  if (process.env.NPORT_BACKEND_URL) {
+    return process.env.NPORT_BACKEND_URL;
+  }
+  
+  // Priority 2: Saved config (will be set by config-manager if available)
+  // Priority 3: Default
+  return "https://api.nport.link";
+}
+
 // Application constants
 export const CONFIG = {
   PACKAGE_NAME: packageJson.name,
   CURRENT_VERSION: packageJson.version,
-  BACKEND_URL: "https://nport.tuanngocptn.workers.dev",
+  BACKEND_URL: getBackendUrl(),
   DEFAULT_PORT: 8080,
   SUBDOMAIN_PREFIX: "user-",
   TUNNEL_TIMEOUT_HOURS: 4,

package/src/lang.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import readline from "readline";
+import { configManager } from "./config-manager.js";
 
 // ============================================================================
 // Language Translations
@@ -10,7 +11,7 @@ import readline from "readline";
 const TRANSLATIONS = {
   en: {
     // Header
-    header: "N P O R T  ⚡️  Free & Open Source from Vietnam",
+    header: "N P O R T  ⚡️  Free & Open Source from Vietnam ❤️",
     
     // Spinners
     creatingTunnel: "Creating tunnel for port {port}...",
@@ -24,7 +25,7 @@ const TRANSLATIONS = {
     
     // Footer
     footerTitle: "🔥 KEEP THE VIBE ALIVE?",
-    footerSubtitle: "(Made with ❤️ in Vietnam)",
+    footerSubtitle: "(Made with ❤️  in Vietnam)",
     dropStar: "⭐️  Drop a Star:   ",
     sendCoffee: "☕️  Buy Coffee:    ",
     newVersion: "🚨 NEW VERSION (v{version}) detected!",
@@ -78,7 +79,7 @@ const TRANSLATIONS = {
     timeRemaining: "⏱️  Tăng tốc thần sầu: Còn {hours}h để quẩy!",
     
     // Footer
-    footerTitle: "🔥 LƯU DANH SỬ SÁCH! KHÔNG QUÊN STAR",
+    footerTitle: "🔥 LƯU DANH SỬ SÁCH! ĐỪNG QUÊN STAR ⭐️",
     footerSubtitle: "(Made in Việt Nam, chuẩn không cần chỉnh! ❤️)",
     dropStar: "⭐️  Thả Star: ",
     sendCoffee: "☕️  Tặng Coffee: ",
@@ -97,7 +98,7 @@ const TRANSLATIONS = {
     goodbyeTitle: "👋 GẶP LẠI BẠN Ở ĐƯỜNG BĂNG KHÁC...",
     goodbyeMessage: "Cảm ơn đã quẩy NPort! Lần sau chơi tiếp nha 😘",
     website: "🌐 Sân chơi chính: ",
-    author: "👤 Nhà tài trợ chương trình: ",
+    author: "👤 Nhà tài trợ: ",
     changeLanguage: "🌍 Đổi ngôn ngữ: ",
     changeLanguageHint: "nport --language",
     
@@ -126,8 +127,6 @@ const TRANSLATIONS = {
 class LanguageManager {
   constructor() {
     this.currentLanguage = "en";
-    this.configDir = path.join(os.homedir(), ".nport");
-    this.configFile = path.join(this.configDir, "lang");
     this.availableLanguages = ["en", "vi"];
   }
 
@@ -154,15 +153,9 @@ class LanguageManager {
    * @returns {string|null} Saved language code or null
    */
   loadLanguagePreference() {
-    try {
-      if (fs.existsSync(this.configFile)) {
-        const lang = fs.readFileSync(this.configFile, "utf8").trim();
-        if (this.availableLanguages.includes(lang)) {
-          return lang;
-        }
-      }
-    } catch (error) {
-      // Ignore errors, will prompt user
+    const lang = configManager.getLanguage();
+    if (lang && this.availableLanguages.includes(lang)) {
+      return lang;
     }
     return null;
   }
@@ -172,16 +165,7 @@ class LanguageManager {
    * @param {string} lang - Language code to save
    */
   saveLanguagePreference(lang) {
-    try {
-      // Ensure .nport directory exists
-      if (!fs.existsSync(this.configDir)) {
-        fs.mkdirSync(this.configDir, { recursive: true });
-      }
-      fs.writeFileSync(this.configFile, lang, "utf8");
-    } catch (error) {
-      // Silently fail if can't save
-      console.warn("Warning: Could not save language preference");
-    }
+    configManager.setLanguage(lang);
   }
 
   /**

package/src/state.js

@@ -7,6 +7,7 @@ class TunnelState {
     this.tunnelId = null;
     this.subdomain = null;
     this.port = null;
+    this.backendUrl = null;
     this.tunnelProcess = null;
     this.timeoutId = null;
     this.connectionCount = 0;
@@ -14,10 +15,11 @@ class TunnelState {
     this.updateInfo = null;
   }
 
-  setTunnel(tunnelId, subdomain, port) {
+  setTunnel(tunnelId, subdomain, port, backendUrl = null) {
     this.tunnelId = tunnelId;
     this.subdomain = subdomain;
     this.port = port;
+    this.backendUrl = backendUrl;
     if (!this.startTime) {
       this.startTime = Date.now();
     }
@@ -65,6 +67,7 @@ class TunnelState {
     this.tunnelId = null;
     this.subdomain = null;
     this.port = null;
+    this.backendUrl = null;
     this.tunnelProcess = null;
     this.connectionCount = 0;
     this.startTime = null;

package/src/tunnel.js

@@ -15,7 +15,7 @@ import { lang } from "./lang.js";
  */
 export class TunnelOrchestrator {
   static async start(config) {
-    state.setTunnel(null, config.subdomain, config.port);
+    state.setTunnel(null, config.subdomain, config.port, config.backendUrl);
 
     // Initialize analytics
     await analytics.initialize();
@@ -42,8 +42,8 @@ export class TunnelOrchestrator {
 
     try {
       // Create tunnel
-      const tunnel = await APIClient.createTunnel(config.subdomain);
-      state.setTunnel(tunnel.tunnelId, config.subdomain, config.port);
+      const tunnel = await APIClient.createTunnel(config.subdomain, config.backendUrl);
+      state.setTunnel(tunnel.tunnelId, config.subdomain, config.port, config.backendUrl);
 
       // Track successful tunnel creation
       analytics.trackTunnelCreated(config.subdomain, config.port);
@@ -101,7 +101,7 @@ export class TunnelOrchestrator {
       }
 
       // Delete tunnel
-      await APIClient.deleteTunnel(state.subdomain, state.tunnelId);
+      await APIClient.deleteTunnel(state.subdomain, state.tunnelId, state.backendUrl);
       UI.displayCleanupSuccess();
     } catch (err) {
       UI.displayCleanupError();

package/src/ui.js

@@ -9,8 +9,13 @@ import { lang } from "./lang.js";
 export class UI {
   static displayProjectInfo() {
     const line = "─".repeat(56);
+    const headerText = lang.t("header");
+    // Calculate proper padding (accounting for emojis which take visual space)
+    const visualLength = 59; // Target visual width
+    const padding = " ".repeat(Math.max(0, visualLength - headerText.length - 4));
+    
     console.log(chalk.gray(`\n ╭${line}╮`));
-    console.log(chalk.cyan.bold(` │  ${lang.t("header")}`) + " ".repeat(56 - lang.t("header").length - 4) + chalk.gray("│"));
+    console.log(chalk.cyan.bold(` │  ${headerText}`) + padding + chalk.gray("│"));
     console.log(chalk.gray(` ╰${line}╯\n`));
   }
 
@@ -95,4 +100,4 @@ export class UI {
     
     console.log(chalk.gray(lang.t("learnMore")) + chalk.cyan("https://nport.link\n"));
   }
-}
+}