{"_id":"@able_k_saju/local-bridge","_rev":"2-1e8e1a1b5da14a0906aa3cb0535f2288","name":"@able_k_saju/local-bridge","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@able_k_saju/local-bridge","version":"1.0.0","keywords":["tunnel","localhost","ngrok","localtunnel","port-forwarding","development","proxy","https","secure","cli"],"author":{"name":"Able K Saju","email":"ableksaju3@gmail.com"},"license":"MIT","_id":"@able_k_saju/local-bridge@1.0.0","maintainers":[{"name":"able_k_saju","email":"ableksaju3@gmail.com"}],"homepage":"https://github.com/ableksaju/Local-Bridge#readme","bugs":{"url":"https://github.com/ableksaju/Local-Bridge/issues"},"bin":{"lb":"bin/cli.js","localbridge":"bin/cli.js"},"dist":{"shasum":"263eadbbb9341107988e96bd97eb29a57ffb419a","tarball":"https://registry.npmjs.org/@able_k_saju/local-bridge/-/local-bridge-1.0.0.tgz","fileCount":7,"integrity":"sha512-Wx42/TrguHzeYSf1LW2xJgWnS64rF41SN9V9CIRj05TMeGIxYY3ENBDjvDYvVad/4JXpgV7elz5j8mQpvnAsyg==","signatures":[{"sig":"MEUCIQDwCBp/4ZEs9cnMrPzjvBneXL+N3bAiOxjq9XTD0fM8jgIgFuAUSzL9qwvvBW6rA9hT2UO1bojihoRJgmwsT6VKMm8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46983},"main":"lib/index.js","engines":{"node":">=14.0.0"},"gitHead":"43845338faad6135dc26d971c38c921d6f4ff7c6","scripts":{"test":"node test/test.js","start":"node bin/cli.js","server":"node lib/server.js","prepublishOnly":"npm test"},"_npmUser":{"name":"able_k_saju","email":"ableksaju3@gmail.com"},"repository":{"url":"git+https://github.com/ableksaju/Local-Bridge.git","type":"git"},"_npmVersion":"10.8.2","description":"A reliable localhost tunneling solution to securely expose your local development server to the internet","directories":{},"_nodeVersion":"20.19.4","dependencies":{"ws":"^8.20.1","cors":"^2.8.5","uuid":"^9.0.0","chalk":"^4.1.2","helmet":"^6.0.1","express":"^4.18.2","commander":"^9.4.1","compression":"^1.7.4"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/local-bridge_1.0.0_1779349035684_0.7540118883129279","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@able_k_saju/local-bridge","version":"1.0.1","description":"A reliable localhost tunneling solution to securely expose your local development server to the internet","main":"lib/index.js","bin":{"localbridge":"bin/cli.js","lb":"bin/cli.js"},"scripts":{"start":"node bin/cli.js","server":"node lib/server.js","test":"node test/test.js","prepublishOnly":"npm test"},"keywords":["tunnel","localhost","ngrok","localtunnel","port-forwarding","development","proxy","https","secure","cli"],"author":{"name":"Able K Saju","email":"ableksaju3@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ableksaju/Local-Bridge.git"},"homepage":"https://github.com/ableksaju/Local-Bridge#readme","bugs":{"url":"https://github.com/ableksaju/Local-Bridge/issues"},"engines":{"node":">=14.0.0"},"dependencies":{"chalk":"^4.1.2","commander":"^9.4.1","compression":"^1.7.4","cors":"^2.8.5","express":"^4.18.2","helmet":"^6.0.1","uuid":"^9.0.0","ws":"^8.20.1"},"_id":"@able_k_saju/local-bridge@1.0.1","gitHead":"600957c69025c8ef16acde738fd1a24d9162a04e","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-CIhX6XTq4s6uEm883FY8EQjnM+oTFnqAx75AVp4ge5ZXpiYQVHgiqJARSo5k2NZHXu1Jti0MflVVnZOAkUs7fQ==","shasum":"45343abdb282cd0ddb16b99be775bc3fe68fce38","tarball":"https://registry.npmjs.org/@able_k_saju/local-bridge/-/local-bridge-1.0.1.tgz","fileCount":7,"unpackedSize":52663,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB8LWhKVJH/KFY9gQPEIADjOjoZEqIS9CSGvqT3CZ/2MAiEAytDmjf5whj0eF5dkFZHlTYAlQal5kKN03JdIWCBQwPU="}]},"_npmUser":{"name":"able_k_saju","email":"ableksaju3@gmail.com"},"directories":{},"maintainers":[{"name":"able_k_saju","email":"ableksaju3@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/local-bridge_1.0.1_1779358460848_0.6279934594222036"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T07:37:15.521Z","modified":"2026-05-21T10:14:21.127Z","1.0.0":"2026-05-21T07:37:15.830Z","1.0.1":"2026-05-21T10:14:21.015Z"},"bugs":{"url":"https://github.com/ableksaju/Local-Bridge/issues"},"author":{"name":"Able K Saju","email":"ableksaju3@gmail.com"},"license":"MIT","homepage":"https://github.com/ableksaju/Local-Bridge#readme","keywords":["tunnel","localhost","ngrok","localtunnel","port-forwarding","development","proxy","https","secure","cli"],"repository":{"type":"git","url":"git+https://github.com/ableksaju/Local-Bridge.git"},"description":"A reliable localhost tunneling solution to securely expose your local development server to the internet","maintainers":[{"name":"able_k_saju","email":"ableksaju3@gmail.com"}],"readme":"# LocalBridge\n\nA reliable, self-hosted localhost tunneling solution to securely expose your local development server to the internet. Similar to ngrok and localtunnel, but designed to be more reliable and user-friendly.\n\n![npm](https://img.shields.io/npm/v/@able_k_saju/local-bridge)\n![npm](https://img.shields.io/npm/dm/@able_k_saju/local-bridge)\n![Node.js](https://img.shields.io/node/v/@able_k_saju/local-bridge)\n![License](https://img.shields.io/npm/l/@able_k_saju/local-bridge)\n\n## Features\n\n- 🚀 **Easy to Use** - Simple CLI commands and programmatic API\n- 🔒 **Secure Tunnels** - WebSocket-based secure connections\n- 🔄 **Auto-Reconnect** - Automatically reconnects on connection loss\n- 💪 **Reliable** - Built-in heartbeat and timeout handling\n- 🎯 **Custom Subdomains** - Support for custom subdomain names\n- 🔑 **Authentication** - Optional token-based authentication\n- 📊 **Status Monitoring** - Check active tunnels with a single command\n- 🌐 **Self-Hosted** - Deploy your own server for full control\n- 📦 **NPM Module** - Easy installation and integration\n\n## Installation\n\n```bash\nnpm install -g @able_k_saju/local-bridge\n```\n\nOr as a local dependency:\n\n```bash\nnpm install @able_k_saju/local-bridge\n```\n\n## Quick Start\n\n### Tunnel a Local App\n\nIf you already have a LocalBridge server running locally or configured with\n`LOCALBRIDGE_SERVER_URL`, tunnel your local app with:\n\n```bash\nlocalbridge 3000 --subdomain myapp\n```\n\nThe CLI command stays `localbridge` even though the npm package is scoped.\n\n### Local Testing\n\nStart both server and tunnel in one command:\n\n```bash\nlocalbridge start 3000 --subdomain myapp\n```\n\n### Hosted Server\n\n**Terminal 1 - Start the server:**\n```bash\nlocalbridge server --domain bridge.example.com --public-protocol https --public-port 443\n```\n\n**Terminal 2 - Create a tunnel:**\n```bash\nlocalbridge 3000 --subdomain myapp --server wss://bridge.example.com\n```\n\nTo avoid typing `--server` every time, set:\n\n```bash\nlocalbridge config wss://bridge.example.com\nlocalbridge 3000 --subdomain myapp\n```\n\nYou can also use `LOCALBRIDGE_SERVER_URL=wss://bridge.example.com` in\nautomation or CI.\n\n## CLI Commands\n\n### `<port>`\nCreate a tunnel to a local port.\n\n```bash\nlocalbridge 3000\nlocalbridge 3000 --subdomain myapp\nlocalbridge 3000 --server wss://bridge.example.com\nlocalbridge 3000 --host 192.168.1.100 --protocol https\n```\n\n### `tunnel <port>` (alias: `t`)\nCreate a tunnel to a local port.\n\n```bash\nlocalbridge tunnel 3000\nlocalbridge tunnel 3000 --subdomain myapp\nlocalbridge tunnel 3000 --server wss://bridge.example.com\nlocalbridge tunnel 3000 --host 192.168.1.100 --protocol https\n```\n\n**Options:**\n- `-s, --subdomain <subdomain>` - Custom subdomain for the tunnel\n- `--server <url>` - LocalBridge server URL (default: `LOCALBRIDGE_SERVER_URL` or `ws://127.0.0.1:8080`)\n- `--host <host>` - Local host to forward to (default: `localhost`)\n- `--protocol <protocol>` - Protocol for local server: http or https (default: `http`)\n- `--auth <token>` - Authentication token for the tunnel\n\n### `server` (alias: `s`)\nStart the LocalBridge server.\n\n```bash\nlocalbridge server\nlocalbridge server --port 9000 --domain my-tunnels.com\nlocalbridge server --domain bridge.example.com --public-protocol https --public-port 443\n```\n\n**Options:**\n- `-p, --port <port>` - Server port (default: `8080`)\n- `-h, --host <host>` - Server host (default: `0.0.0.0`)\n- `-d, --domain <domain>` - Domain for tunnels (default: `localhost`)\n- `--public-protocol <protocol>` - Protocol shown in public tunnel URLs (default: `http`, or `https` on Render)\n- `--public-port <port>` - Public port shown in tunnel URLs (default: server port, or `443` for HTTPS)\n\n### `start <port>` (alias: `run`)\nStart both server and tunnel (for local testing).\n\n```bash\nlocalbridge start 3000\nlocalbridge start 3000 --subdomain myapp --server-port 9000\n```\n\n**Options:**\n- `--subdomain <subdomain>` - Custom subdomain for the tunnel\n- `--host <host>` - Local host to forward to (default: `localhost`)\n- `--protocol <protocol>` - Protocol for local server (default: `http`)\n- `--server-port <port>` - Server port (default: `8080`)\n\n### `status`\nShow status of active tunnels.\n\n```bash\nlocalbridge status\nlocalbridge status --server http://custom-server.com:8080\n```\n\n### `config [serverUrl]`\nShow or save the default hosted LocalBridge server URL.\n\n```bash\nlocalbridge config\nlocalbridge config wss://bridge.example.com\n```\n\n### `list`\nList all available commands with examples.\n\n```bash\nlocalbridge list\n```\n\n## Programmatic Usage\n\nLocalBridge can also be used as a Node.js module:\n\n```javascript\nconst localbridge = require('@able_k_saju/local-bridge');\n\n// Create a tunnel\nconst client = await localbridge.tunnel(3000, {\n    serverUrl: 'ws://your-server.com:8080',\n    subdomain: 'myapp',\n    authToken: 'secret-token'\n});\n\nconsole.log('Public URL:', client.publicUrl);\n\n// Keep the process running\nsetTimeout(() => {}, Infinity);\n```\n\n### Starting a Server Programmatically\n\n```javascript\nconst localbridge = require('@able_k_saju/local-bridge');\n\nconst server = await localbridge.createServer({\n    port: 8080,\n    domain: 'your-domain.com'\n});\n\nconsole.log('Server started');\n```\n\n### Using Classes Directly\n\n```javascript\nconst { LocalBridgeServer, LocalBridgeClient } = require('@able_k_saju/local-bridge');\n\n// Create server\nconst server = new LocalBridgeServer({ port: 8080 });\nawait server.start();\n\n// Create client\nconst client = new LocalBridgeClient({\n    serverUrl: 'ws://localhost:8080',\n    localPort: 3000\n});\nawait client.connect();\n```\n\n## Configuration\n\n### Server Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `port` | `8080` | Port for the server to listen on |\n| `host` | `0.0.0.0` | Host address to bind to |\n| `domain` | `localhost` | Domain used for tunnel URLs |\n\n### Client Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `serverUrl` | `ws://localhost:8080` | WebSocket URL of the server |\n| `localPort` | `3000` | Local port to forward to |\n| `localHost` | `localhost` | Local host to forward to |\n| `subdomain` | Random | Custom subdomain for the tunnel |\n| `authToken` | `null` | Authentication token |\n| `protocol` | `http` | Protocol for local server (http/https) |\n| `reconnectInterval` | `3000` | Milliseconds between reconnect attempts |\n| `maxReconnectAttempts` | `Infinity` | Maximum reconnection attempts |\n| `requestTimeout` | `30000` | Request timeout in milliseconds |\n\n## Security\n\n### Authentication\n\nLocalBridge supports optional token-based authentication. Set an auth token when creating a tunnel:\n\n```bash\nlocalbridge tunnel 3000 --auth my-secret-token\n```\n\n### Self-Hosted\n\nOne of the key advantages of LocalBridge is that you can host your own server, giving you full control over your data and tunnels.\n\n### HTTPS Support\n\nFor production use, you should:\n1. Deploy LocalBridge as a long-running Node.js web service\n2. Point both `bridge.example.com` and `*.bridge.example.com` to that service\n3. Use HTTPS/WSS at the public edge\n4. Start the server with `--public-protocol https --public-port 443`\n\nRender is a good fit because it supports long-running Node.js web services and\nWebSockets. Vercel and Netlify serverless functions are not a good fit for the\nLocalBridge server because the tunnel depends on persistent WebSocket\nconnections.\n\nExample Render start command:\n\n```bash\nlocalbridge server --port $PORT --domain bridge.example.com --public-protocol https --public-port 443\n```\n\n## Architecture\n\n```\n┌─────────────────┐         WebSocket         ┌─────────────────┐\n│                 │  ═══════════════════════> │                 │\n│  External User  │                           │  LocalBridge    │\n│                 │  <═══════════════════════ │     Client      │\n└────────┬────────┘         HTTP/HTTPS        └────────┬────────┘\n         │                                             │\n         │ HTTP/HTTPS                                  │ HTTP/HTTPS\n         ▼                                             ▼\n┌─────────────────┐                           ┌─────────────────┐\n│                 │                           │                 │\n│ LocalBridge     │                           │   Your Local    │\n│     Server      │                           │     Server      │\n│                 │                           │   (localhost)   │\n└─────────────────┘                           └─────────────────┘\n```\n\n1. **External User** makes a request to the public tunnel URL\n2. **LocalBridge Server** receives the request and forwards it through the WebSocket tunnel\n3. **LocalBridge Client** receives the request and forwards it to the local server\n4. **Your Local Server** processes the request and sends the response back\n5. The response flows back through the same path to the external user\n\n## Troubleshooting\n\n### Connection Refused\n\nIf you see \"Connection refused\" errors:\n1. Make sure the LocalBridge server is running\n2. Check that the server URL is correct\n3. Verify the port is not blocked by a firewall\n\n### Tunnel Not Available\n\nIf you see \"Tunnel not available\":\n1. Check that the client is connected\n2. Verify the subdomain is correct\n3. Try creating a new tunnel with a different subdomain\n\n### Timeout Errors\n\nIf requests are timing out:\n1. Check that your local server is responding\n2. Increase the request timeout: `--request-timeout 60000`\n3. Verify network connectivity\n\n### Reconnection Issues\n\nIf the tunnel keeps disconnecting:\n1. Check network stability\n2. Increase reconnect interval: Create client with `reconnectInterval: 5000`\n3. Check server logs for errors\n\n## Comparison with Similar Tools\n\n| Feature | LocalBridge | ngrok | localtunnel |\n|---------|-------------|-------|-------------|\n| Self-hosted | ✅ Yes | ❌ No (paid) | ✅ Yes |\n| Free | ✅ Yes | ❌ Limited | ✅ Yes |\n| Custom domains | ✅ Yes | ❌ Paid | ❌ No |\n| Auto-reconnect | ✅ Yes | ✅ Yes | ⚠️ Unreliable |\n| Authentication | ✅ Yes | ✅ Yes | ❌ No |\n| Easy CLI | ✅ Yes | ✅ Yes | ✅ Yes |\n| NPM module | ✅ Yes | ✅ Yes | ✅ Yes |\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\nIf you encounter any issues or have questions:\n\n- Open an issue on [GitHub](https://github.com/ableksaju/Local-Bridge/issues)\n- Check the [documentation](https://github.com/ableksaju/Local-Bridge#readme)\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- CLI with tunnel, server, start, and status commands\n- WebSocket-based tunneling\n- Auto-reconnect functionality\n- Authentication support\n- Programmatic API\n","readmeFilename":"README.md"}