Skip to main content

​
When to Use the Programmatic API

The Portless programmatic API allows you to embed the proxy server directly into your Node.js application. Use this when:
  • You need custom routing logic beyond hostname-based matching
  • You want to integrate Portless into an existing Node.js tool or framework
  • You need programmatic control over route registration and lifecycle
  • You’re building a development platform that manages multiple services
For most use cases, the CLI is the recommended approach. Only use the programmatic API if you need custom integration.

​
Installation

Install Portless as a dependency in your project: 
npm install portless

​
Basic Usage

Here’s a minimal example that creates a proxy server and registers a route: 
import { createProxyServer, RouteStore } from "portless";

const store = new RouteStore("/tmp/portless-state");
store.ensureDir();

// Register a route: api.localhost -> localhost:3000
store.addRoute("api.localhost", 3000, process.pid);

// Create the proxy server
const server = createProxyServer({
  getRoutes: () => store.loadRoutes(),
  proxyPort: 8080,
  onError: (msg) => console.error(msg),
});

server.listen(8080, () => {
  console.log("Proxy server listening on port 8080");
});

// Cleanup on exit
process.on("SIGINT", () => {
  store.removeRoute("api.localhost");
  server.close();
  process.exit(0);
});

​
Key Components

The Portless API consists of three main components:

createProxyServer

Create an HTTP/HTTPS proxy server with hostname-based routing

RouteStore

Manage route mappings with file-based persistence

Type Definitions

TypeScript interfaces for routes and configuration

​
Next Steps

Proxy Server

Learn how to create and configure proxy servers

Route Management

Understand route registration and persistence

Build docs developers (and LLMs) love

Get started for freeTalk to us