Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pipenet
✓ import { pipenet } from 'pipenet';
✗ const pipenet = require('pipenet');
The primary client function is a named export. Node.js >=22.0.0 promotes ESM usage.
createServer
✓ import { createServer } from 'pipenet/server';
✗ import { createServer } from 'pipenet';
The server component's factory function is exported from a dedicated subpath.
Tunnel
✓ import type { Tunnel } from 'pipenet';
✗ import { Tunnel } from 'pipenet';
Use 'import type' for the Tunnel instance interface when working in TypeScript.
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.
import { pipenet } from 'pipenet';
import http from 'http';
import { AddressInfo } from 'net'; // For checking server address
async function startPipenetTunnel() {
// Create a simple local HTTP server to expose
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end(`Hello from pipenet! Requested path: ${req.url}\n`);
});
const localPort = 3000;
server.listen(localPort, () => {
const address = server.address() as AddressInfo;
console.log(`Local HTTP server listening on ${address.address}:${address.port}`);
});
try {
// Create a pipenet tunnel to expose the local server
const tunnel = await pipenet({
port: localPort,
// host: 'https://pipenet.dev', // Defaults to pipenet.dev if not specified
subdomain: `my-test-app-${Math.random().toString(36).substring(2, 7)}` // Request a dynamic subdomain
});
console.log(`PTP Tunnel established! Public URL: ${tunnel.url}`);
tunnel.on('request', (info) => {
console.log(`[Tunnel Event] Request processed: ${info.method} ${info.path}`);
});
tunnel.on('error', (err) => {
console.error('[Tunnel Event] An error occurred:', err.message);
});
tunnel.on('close', () => {
console.log('[Tunnel Event] Tunnel has closed. Shutting down local server...');
server.close(() => console.log('Local server closed.'));
});
// Automatically close the tunnel after a period (e.g., 60 seconds) for demonstration
setTimeout(() => {
console.log('Automatically closing tunnel after 60 seconds...');
tunnel.close();
}, 60000);
} catch (error: any) {
console.error('Failed to create pipenet tunnel:', error.message);
server.close();
}
}
startPipenetTunnel();
pipenet --version
Debug
Known issues
gotchaSubdomain requests are not guaranteed. While you can request a specific subdomain, its availability is not guaranteed, and you might receive a different public URL.fixDesign 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.
affects: >=1.0.0
breakingRequires 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.fixEnsure 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.
affects: >=1.0.0
gotchaCLI 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.fixReview 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.
affects: <1.2.1 to >=1.2.1
gotchaThe package is primarily designed for ES Modules (ESM) usage in modern Node.js environments (>=22.0.0).fixAdopt 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: connect ECONNREFUSED ::1:3000
The local server pipenet is trying to expose is not running or not listening on the specified port.
fixEnsure your local application is actively listening on the specified port (e.g., 3000) before starting the pipenet tunnel client.
Failed to create pipenet tunnel: Subdomain 'myapp' already taken.
The requested subdomain is already in use by another client on the pipenet server.
fixOmit the `subdomain` option to receive a randomly generated public URL, or try a different, unique subdomain name.
Error: Your Node.js version (vX.Y.Z) is not supported. pipenet requires Node.js >=22.0.0.
The installed Node.js version on your system does not meet the minimum requirement specified by pipenet.
fixUpgrade your Node.js environment to version 22.0.0 or higher. Tools like nvm (Node Version Manager) can help manage multiple Node.js versions.
Audit
Dependencies
No dependency data recorded yet.