{"id":11556,"library":"pipenet","title":"pipenet","description":"pipenet is a Node.js library and CLI tool designed to instantly expose local development servers to the public internet, facilitating testing and collaboration without complex network configurations. Currently at version 1.4.0, the project demonstrates an active release cadence with several updates in early 2026, including features like adding hooks and shared tunnel server capabilities for cloud deployments. It offers both a command-line interface for quick usage and a programmatic API for deeper integration into automated workflows or testing environments. Key differentiators include the ability to request specific subdomains, support for custom upstream tunnel servers, and the option to run a self-hosted pipenet server with custom domains and multiple domain support, providing flexibility for various deployment scenarios. It ships with TypeScript types, promoting better developer experience in typed environments.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/punkpeye/pipenet","tags":["javascript","typescript"],"install":[{"cmd":"npm install pipenet","lang":"bash","label":"npm"},{"cmd":"yarn add pipenet","lang":"bash","label":"yarn"},{"cmd":"pnpm add pipenet","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary client function is a named export. Node.js >=22.0.0 promotes ESM usage.","wrong":"const pipenet = require('pipenet');","symbol":"pipenet","correct":"import { pipenet } from 'pipenet';"},{"note":"The server component's factory function is exported from a dedicated subpath.","wrong":"import { createServer } from 'pipenet';","symbol":"createServer","correct":"import { createServer } from 'pipenet/server';"},{"note":"Use 'import type' for the Tunnel instance interface when working in TypeScript.","wrong":"import { Tunnel } from 'pipenet';","symbol":"Tunnel","correct":"import type { Tunnel } from 'pipenet';"}],"quickstart":{"code":"import { pipenet } from 'pipenet';\nimport http from 'http';\nimport { AddressInfo } from 'net'; // For checking server address\n\nasync function startPipenetTunnel() {\n  // Create a simple local HTTP server to expose\n  const server = http.createServer((req, res) => {\n    res.writeHead(200, { 'Content-Type': 'text/plain' });\n    res.end(`Hello from pipenet! Requested path: ${req.url}\\n`);\n  });\n\n  const localPort = 3000;\n  server.listen(localPort, () => {\n    const address = server.address() as AddressInfo;\n    console.log(`Local HTTP server listening on ${address.address}:${address.port}`);\n  });\n\n  try {\n    // Create a pipenet tunnel to expose the local server\n    const tunnel = await pipenet({\n      port: localPort,\n      // host: 'https://pipenet.dev', // Defaults to pipenet.dev if not specified\n      subdomain: `my-test-app-${Math.random().toString(36).substring(2, 7)}` // Request a dynamic subdomain\n    });\n\n    console.log(`PTP Tunnel established! Public URL: ${tunnel.url}`);\n\n    tunnel.on('request', (info) => {\n      console.log(`[Tunnel Event] Request processed: ${info.method} ${info.path}`);\n    });\n\n    tunnel.on('error', (err) => {\n      console.error('[Tunnel Event] An error occurred:', err.message);\n    });\n\n    tunnel.on('close', () => {\n      console.log('[Tunnel Event] Tunnel has closed. Shutting down local server...');\n      server.close(() => console.log('Local server closed.'));\n    });\n\n    // Automatically close the tunnel after a period (e.g., 60 seconds) for demonstration\n    setTimeout(() => {\n      console.log('Automatically closing tunnel after 60 seconds...');\n      tunnel.close();\n    }, 60000);\n\n  } catch (error: any) {\n    console.error('Failed to create pipenet tunnel:', error.message);\n    server.close();\n  }\n}\n\nstartPipenetTunnel();","lang":"typescript","description":"This example demonstrates how to programmatically create a pipenet tunnel, exposing a basic local HTTP server to the public internet. It illustrates awaiting the tunnel URL, logging incoming requests, and handling potential errors or the tunnel's closure, providing a complete, runnable setup for integrating `pipenet` into a Node.js application."},"warnings":[{"fix":"Design your application to handle dynamically assigned URLs. Always use `tunnel.url` for the actual public address, and gracefully handle cases where your preferred subdomain is unavailable.","message":"Subdomain requests are not guaranteed. While you can request a specific subdomain, its availability is not guaranteed, and you might receive a different public URL.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment is version 22.0.0 or higher. Use a version manager like nvm or fnm to switch or upgrade your Node.js version.","message":"Requires Node.js version 22.0.0 or higher. Running pipenet on older Node.js versions will result in an error or unexpected behavior due to engine requirements.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Review CLI usage after upgrading to v1.2.1 or later, specifically checking option names for server configurations or client commands, as a bug fix in option naming was applied.","message":"CLI option name changed for bug fix in v1.2.1. Users upgrading from versions prior to 1.2.1 might encounter issues if they were using the previously incorrect CLI option name.","severity":"gotcha","affected_versions":"<1.2.1 to >=1.2.1"},{"fix":"Adopt ES module syntax (import/export) in your Node.js projects. If you must use CommonJS (require()), ensure your project is configured correctly for interoperability, though direct `require()` might not work for all exports.","message":"The package is primarily designed for ES Modules (ESM) usage in modern Node.js environments (>=22.0.0).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your local application is actively listening on the specified port (e.g., 3000) before starting the pipenet tunnel client.","cause":"The local server pipenet is trying to expose is not running or not listening on the specified port.","error":"Error: connect ECONNREFUSED ::1:3000"},{"fix":"Omit the `subdomain` option to receive a randomly generated public URL, or try a different, unique subdomain name.","cause":"The requested subdomain is already in use by another client on the pipenet server.","error":"Failed to create pipenet tunnel: Subdomain 'myapp' already taken."},{"fix":"Upgrade your Node.js environment to version 22.0.0 or higher. Tools like nvm (Node Version Manager) can help manage multiple Node.js versions.","cause":"The installed Node.js version on your system does not meet the minimum requirement specified by pipenet.","error":"Error: Your Node.js version (vX.Y.Z) is not supported. pipenet requires Node.js >=22.0.0."}],"ecosystem":"npm"}