portpreview 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -251
- package/package.json +9 -5
package/README.md
CHANGED
|
@@ -1,278 +1,101 @@
|
|
|
1
1
|
# PortPreview CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/portpreview)
|
|
4
|
+
[](LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
That connects to the PortPreview gateway and forwards public traffic to `http://127.0.0.1:3000`.
|
|
12
|
-
|
|
13
|
-
## Install in this repo
|
|
14
|
-
|
|
15
|
-
From the project root:
|
|
6
|
+
Open-source localhost tunnel client for [PortPreview](https://portpreview.com).
|
|
7
|
+
One command gives a local HTTP server a public HTTPS URL on `*.portpreview.dev`
|
|
8
|
+
for webhook debugging, OAuth callbacks, and client or mobile previews — without
|
|
9
|
+
deploying to staging.
|
|
16
10
|
|
|
17
11
|
```bash
|
|
18
|
-
npm install
|
|
19
12
|
npx portpreview 3000
|
|
20
13
|
```
|
|
21
14
|
|
|
22
|
-
`npx` picks up the local CLI from `node_modules/.bin` before hitting the npm registry.
|
|
23
|
-
|
|
24
|
-
## Publish to npm
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
cd cli
|
|
28
|
-
npm login
|
|
29
|
-
npm publish
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
After the current package version is published to npm, `npx portpreview 3000` works from any directory without cloning this repo.
|
|
33
|
-
|
|
34
|
-
## Standalone Windows x64
|
|
35
|
-
|
|
36
|
-
The standalone executable includes Node.js and the same CLI used by npm. On a
|
|
37
|
-
verified release, download the versioned `.exe` and its `.sha256` file, check the
|
|
38
|
-
hash with `Get-FileHash`, then run in PowerShell:
|
|
39
|
-
|
|
40
|
-
```powershell
|
|
41
|
-
.\portpreview-0.2.0-windows-x64.exe --help
|
|
42
|
-
.\portpreview-0.2.0-windows-x64.exe 3000
|
|
43
|
-
.\portpreview-0.2.0-windows-x64.exe config set-token pp_live_...
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
No Node.js or npm installation is needed to run the executable. Windows tokens
|
|
47
|
-
are stored in `%LOCALAPPDATA%\portpreview\config.json` by default. Current builds
|
|
48
|
-
are unsigned. Download availability depends on successful Windows verification;
|
|
49
|
-
a cross-built artifact alone is not a verified release. See
|
|
50
|
-
[Windows packaging and release checks](packaging/README.md).
|
|
51
|
-
|
|
52
|
-
## Local development (no production gateway)
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
# Terminal 1 — dev gateway
|
|
56
|
-
npm run gateway --prefix cli
|
|
57
|
-
|
|
58
|
-
# Terminal 2 — your app
|
|
59
|
-
python3 -m http.server 3000
|
|
60
|
-
|
|
61
|
-
# Terminal 3 — tunnel
|
|
62
|
-
npx portpreview 3000 \
|
|
63
|
-
--gateway ws://127.0.0.1:4040/tunnel \
|
|
64
|
-
--domain localhost:4040
|
|
65
15
|
```
|
|
66
|
-
|
|
67
|
-
## Options
|
|
68
|
-
|
|
69
|
-
| Flag | Description |
|
|
70
|
-
|------|-------------|
|
|
71
|
-
| `--host` | Local address to forward to (default `127.0.0.1`) |
|
|
72
|
-
| `--subdomain` | Use a name reserved in your dashboard |
|
|
73
|
-
| `--token` | Authenticate with a dashboard CLI token |
|
|
74
|
-
| `--inspect` / `--no-inspect` | Turn the local request inspector on or off (default: on, off with `--quiet`) |
|
|
75
|
-
| `--inspect-port <n>` | Inspector port on `127.0.0.1` (default `4041`) |
|
|
76
|
-
| `-q, --quiet` | Print only the public URL |
|
|
77
|
-
| `-h, --help` | Show help |
|
|
78
|
-
| `-v, --version` | Show version |
|
|
79
|
-
|
|
80
|
-
## Environment
|
|
81
|
-
|
|
82
|
-
| Variable | Description |
|
|
83
|
-
|----------|-------------|
|
|
84
|
-
| `PORTPREVIEW_TOKEN` | CLI token used for reserved subdomains |
|
|
85
|
-
| `PORTPREVIEW_CONFIG` | Override local config file path |
|
|
86
|
-
| `PORTPREVIEW_INSPECT` | `1` or `0` to turn the request inspector on or off |
|
|
87
|
-
| `PORTPREVIEW_INSPECT_PORT` | Request inspector port (default `4041`) |
|
|
88
|
-
|
|
89
|
-
See **Local development** below for `--gateway`, `--domain`, and related env vars.
|
|
90
|
-
|
|
91
|
-
## TCP tunnels (paid plans)
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
npx portpreview config set-token pp_live_...
|
|
95
|
-
npx portpreview tcp 5432
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
```
|
|
99
|
-
URL: tcp://tcp.portpreview.dev:20017
|
|
100
|
-
Target: 127.0.0.1:5432
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Raw TCP for databases, SSH and other non-HTTP services. Available on Pro, Ultra and Team; each
|
|
104
|
-
account has one stable port, so the address is the same on every run and one TCP tunnel can run at
|
|
105
|
-
a time. Up to 50 concurrent connections, at most 10 from one source address; a connection with no
|
|
106
|
-
traffic for 30 minutes is closed.
|
|
107
|
-
Each closed connection is logged with its duration and byte counts.
|
|
108
|
-
|
|
109
|
-
PortPreview adds no TLS and no password on the public side of a TCP tunnel: anyone who knows the
|
|
110
|
-
address can connect, so expose only services that authenticate and encrypt connections themselves.
|
|
111
|
-
There is no UDP, and the request inspector does not apply to TCP tunnels.
|
|
112
|
-
|
|
113
|
-
Self-hosted gateways enable TCP tunnels with `PORTPREVIEW_TCP_PORTS=20000-20099` (the public port
|
|
114
|
-
range), optionally `PORTPREVIEW_TCP_HOST` and `PORTPREVIEW_TCP_PUBLIC_HOST`.
|
|
115
|
-
|
|
116
|
-
## Local request inspector
|
|
117
|
-
|
|
118
|
-
While the tunnel runs, the CLI serves a local web UI that lists every request that
|
|
119
|
-
reached it, with headers and bodies, and can replay a request against your app:
|
|
120
|
-
|
|
121
|
-
```text
|
|
122
|
-
Connected
|
|
123
|
-
URL: https://abc12.portpreview.dev
|
|
124
|
-
Inspect: http://127.0.0.1:4041
|
|
16
|
+
URL: https://jjm5s.portpreview.dev
|
|
125
17
|
Target: http://127.0.0.1:3000
|
|
126
18
|
```
|
|
127
19
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
- **
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
- **
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
as a new entry marked `edited` and linked to the original, and the terminal logs it
|
|
152
|
-
with a `(replay, edited)` suffix. `Host`, `Connection`, `Content-Length` and
|
|
153
|
-
`Transfer-Encoding` are always regenerated, whatever the editor contains. Limits:
|
|
154
|
-
1 MiB body, 200 headers and 64 KiB of headers in total, 8 KiB path.
|
|
155
|
-
- **Copy as cURL** builds a command for the local target or the public URL. It
|
|
156
|
-
contains the captured header values, so treat it as a secret.
|
|
157
|
-
- **Limits:** the newest 200 entries, 1 MiB per request body, 256 KiB per response
|
|
158
|
-
body and 32 MiB in total; larger bodies are marked truncated (the app and the
|
|
159
|
-
visitor still get every byte). Data lives only in the CLI's memory and is gone when
|
|
160
|
-
it exits. Only requests that reached this CLI appear; requests the gateway rejects
|
|
161
|
-
(body too large, preview password, IP allowlist, tunnel offline) do not.
|
|
162
|
-
- **Port:** `4041` by default. If it is busy the CLI tries 4042–4050 and then a random
|
|
163
|
-
free port, and prints the one it got. A port set with `--inspect-port` or
|
|
164
|
-
`PORTPREVIEW_INSPECT_PORT` is used as is: if it is busy the CLI prints a warning
|
|
165
|
-
and runs without the inspector. The inspector never stops or delays the tunnel.
|
|
166
|
-
- **On by default** for interactive runs. `--quiet` turns it off unless you also pass
|
|
167
|
-
`--inspect` (the `Inspect:` line then goes to stderr, so stdout stays just the URL).
|
|
168
|
-
Library callers of `openTunnel` get no inspector unless they pass one (see below).
|
|
20
|
+
No signup and no config file. Requires Node.js 18 or newer.
|
|
21
|
+
|
|
22
|
+
## What you get
|
|
23
|
+
|
|
24
|
+
- **Public HTTPS URL** that forwards to `http://127.0.0.1:<port>`; visitors see
|
|
25
|
+
your app directly, with no warning or interstitial page.
|
|
26
|
+
- **Live request log** in the terminal: method, path, status, and response time
|
|
27
|
+
of every request, e.g. `POST /webhooks/stripe 200 19ms`.
|
|
28
|
+
- **Local request inspector** at `http://127.0.0.1:4041` while the CLI runs: headers,
|
|
29
|
+
bodies, copy as cURL, replay, and edit-and-replay against your app. No account;
|
|
30
|
+
nothing leaves your machine.
|
|
31
|
+
- **Webhook-safe forwarding**: raw bodies and headers reach your app unchanged,
|
|
32
|
+
so Stripe and GitHub signature checks pass. `Host` is rewritten to
|
|
33
|
+
`127.0.0.1:<port>`, so Vite and similar dev servers need no `allowedHosts` change.
|
|
34
|
+
- **WebSocket, Server-Sent Events, and HMR** through the tunnel.
|
|
35
|
+
- **Streaming bodies** with no total size limit, and automatic reconnect with
|
|
36
|
+
backoff after network loss.
|
|
37
|
+
- **No session time limit** on any plan.
|
|
38
|
+
|
|
39
|
+
With a free account you also get a reserved subdomain, request history in the web
|
|
40
|
+
dashboard, and password or IP allowlist protection for previews. Paid plans add raw
|
|
41
|
+
TCP tunnels: `npx portpreview tcp 5432` gives `tcp.portpreview.dev:<port>`. See
|
|
42
|
+
[pricing](https://portpreview.com/pricing).
|
|
169
43
|
|
|
170
|
-
|
|
171
|
-
local inspector: any program on this machine can read it. It rejects requests whose
|
|
172
|
-
`Host` is not `127.0.0.1:<port>`, `localhost:<port>` or `[::1]:<port>` (DNS
|
|
173
|
-
rebinding), never sends CORS headers, and accepts replay, edited replay and clear only
|
|
174
|
-
with an `X-PortPreview-Inspector: 1` header, `Content-Type: application/json` and a
|
|
175
|
-
matching `Origin`, so other websites cannot trigger them. Pages use a nonce-based CSP and
|
|
176
|
-
render captured data as text only; raw bodies download as attachments. The values of
|
|
177
|
-
`Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` and `X-API-Key` are
|
|
178
|
-
hidden on screen until clicked; they are stored unmodified because replay needs them.
|
|
179
|
-
On a shared machine where you do not trust other local users, run with `--no-inspect`.
|
|
180
|
-
|
|
181
|
-
**Edited replay from a script.** The editor uses `POST /api/replay`, which answers
|
|
182
|
-
`{ "id": <new entry id> }`:
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
curl http://127.0.0.1:4041/api/replay \
|
|
186
|
-
-H 'X-PortPreview-Inspector: 1' -H 'Content-Type: application/json' \
|
|
187
|
-
-d '{"replayOf":12,"method":"POST","path":"/webhooks/stripe",
|
|
188
|
-
"headers":[["Content-Type","application/json"],["X-Dup","a"],["X-Dup","b"]],
|
|
189
|
-
"body":"{\"type\":\"invoice.paid\"}"}'
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
`headers` is a list of `[name, value]` pairs (repeated names are sent as separate
|
|
193
|
-
lines) or an object; `body` is UTF-8 text, or base64 with `"bodyEncoding": "base64"`;
|
|
194
|
-
`replayOf` is optional. Invalid input gets `400` with a message (method outside the
|
|
195
|
-
list, a path that does not start with a single `/` or contains a backslash, spaces or
|
|
196
|
-
control characters, a header name that is not an HTTP token, CR/LF/NUL in a value,
|
|
197
|
-
unknown fields); a body over 1 MiB, or a request over 3 MiB, gets `413`.
|
|
198
|
-
|
|
199
|
-
Library use:
|
|
200
|
-
|
|
201
|
-
```js
|
|
202
|
-
import { openTunnel, createInspectorStore, startInspectorServer } from 'portpreview'
|
|
203
|
-
|
|
204
|
-
const store = createInspectorStore()
|
|
205
|
-
const tunnel = await openTunnel({ port: 3000, host: '127.0.0.1', gatewayUrl, tunnelDomain, quiet: true, inspector: store })
|
|
206
|
-
const inspector = await startInspectorServer({ store, target: { host: '127.0.0.1', port: 3000 }, port: 4041 })
|
|
207
|
-
console.log(inspector.url)
|
|
208
|
-
await tunnel.closed
|
|
209
|
-
await inspector.close()
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
The server does not keep the process alive on its own.
|
|
213
|
-
|
|
214
|
-
## Persistent token (recommended)
|
|
44
|
+
## Usage
|
|
215
45
|
|
|
216
46
|
```bash
|
|
217
|
-
npx portpreview
|
|
218
|
-
npx portpreview
|
|
219
|
-
npx portpreview
|
|
47
|
+
npx portpreview 3000 # random subdomain
|
|
48
|
+
npx portpreview config set-token pp_live_... # save a CLI token from the dashboard
|
|
49
|
+
npx portpreview 3000 --subdomain my-app # reserved subdomain
|
|
50
|
+
npx portpreview tcp 5432 # raw TCP tunnel (paid plans)
|
|
220
51
|
```
|
|
221
52
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
53
|
+
| Option | Description |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `--host <addr>` | Local address to forward to (default `127.0.0.1`) |
|
|
56
|
+
| `--subdomain <name>` | Use a subdomain reserved by your account |
|
|
57
|
+
| `--token <token>` | Authenticate with a CLI token |
|
|
58
|
+
| `--gateway <url>` | Gateway WebSocket URL (default `wss://gateway.portpreview.dev/tunnel`) |
|
|
59
|
+
| `--domain <domain>` | Public tunnel domain (default `portpreview.dev`) |
|
|
60
|
+
| `--no-inspect` / `--inspect-port <n>` | Turn the local inspector off, or choose its port (default `4041`) |
|
|
61
|
+
| `-q, --quiet` | Print only the public URL |
|
|
62
|
+
| `-h, --help` / `-v, --version` | Help and version |
|
|
227
63
|
|
|
228
|
-
|
|
64
|
+
| Environment variable | Description |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `PORTPREVIEW_TOKEN` | CLI token |
|
|
67
|
+
| `PORTPREVIEW_CONFIG` | Config file path (default `~/.config/portpreview/config.json` on Linux) |
|
|
68
|
+
| `PORTPREVIEW_GATEWAY_URL` | Gateway WebSocket URL |
|
|
69
|
+
| `PORTPREVIEW_TUNNEL_DOMAIN` | Public tunnel domain |
|
|
229
70
|
|
|
230
|
-
|
|
231
|
-
|
|
71
|
+
If your server listens only on IPv6 `::1` (default Vite), start it with
|
|
72
|
+
`--host 127.0.0.1` or pass `--host ::1` to the CLI.
|
|
232
73
|
|
|
233
|
-
|
|
234
|
-
RUN_LARGE_STREAM_TEST=1 node --test --test-concurrency=1 cli/test/streaming.test.mjs
|
|
74
|
+
## Limits
|
|
235
75
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
76
|
+
- HTTP and WebSocket on every plan; raw TCP on paid plans; no UDP.
|
|
77
|
+
- WebSocket messages up to 1 MiB each.
|
|
78
|
+
- Streams with no progress for 120 seconds are closed.
|
|
79
|
+
- One gateway region (Tokyo, Japan).
|
|
80
|
+
- The local inspector keeps the last 200 requests in memory; the dashboard stores
|
|
81
|
+
the first 64 KiB of each body.
|
|
82
|
+
- A tunnel URL is not a secret: its TLS certificate is listed in public Certificate
|
|
83
|
+
Transparency logs, so scanners usually find a new URL within minutes. Do not expose
|
|
84
|
+
debug endpoints; protect reserved previews with a password or an IP allowlist.
|
|
239
85
|
|
|
240
|
-
|
|
86
|
+
Full reference: [portpreview.com/docs](https://portpreview.com/docs).
|
|
241
87
|
|
|
242
|
-
|
|
243
|
-
Tunnel sessions have no duration limit on any plan. Self-hosted gateways older
|
|
244
|
-
than 0.2.0 can retain their previous session limits until they are upgraded.
|
|
88
|
+
## What is open source
|
|
245
89
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
window; the hosted dashboard captures only the first 64 KiB and marks incomplete previews.
|
|
250
|
-
Range, If-Range, ETag, Content-Range and original Content-Length are preserved,
|
|
251
|
-
including 206/416 and HEAD. Streams with no progress for 120 seconds are
|
|
252
|
-
cancelled; active slow streams may continue indefinitely. Tunnel transport
|
|
253
|
-
heartbeats detect dead connections. After transient network loss, the CLI
|
|
254
|
-
reconnects automatically with exponential backoff and jitter, from 500 ms up to
|
|
255
|
-
30 seconds. Anonymous tunnels may receive a new URL, which the command announces;
|
|
256
|
-
reserved tunnels retry with the same subdomain and token. Access revocation and
|
|
257
|
-
permanent registration or authentication errors stop retries. Ctrl+C cancels
|
|
258
|
-
pending connection attempts and retry timers.
|
|
90
|
+
This repository contains the CLI client published to npm as
|
|
91
|
+
[`portpreview`](https://www.npmjs.com/package/portpreview). The hosted gateway,
|
|
92
|
+
dashboard, request history, and billing are not open source.
|
|
259
93
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
`onReconnect` callback.
|
|
94
|
+
`npm test` here covers argument parsing, the wire protocol, the token store and a
|
|
95
|
+
tunnel against a small fixture gateway. The streaming, reconnect, inspector and TCP
|
|
96
|
+
suites need the hosted gateway code and run in the private repository before each
|
|
97
|
+
release.
|
|
265
98
|
|
|
266
|
-
|
|
267
|
-
1 MiB HTTP body cap; both ends need upgrading for streaming. WebSocket messages
|
|
268
|
-
retain an explicit 1 MiB per-message limit; oversized messages close rather than
|
|
269
|
-
silently truncate. Requests made by automated agents and webhooks are included
|
|
270
|
-
in request history.
|
|
99
|
+
## License
|
|
271
100
|
|
|
272
|
-
|
|
273
|
-
dashboard (all plans). A password uses HTTP Basic authentication; enter any
|
|
274
|
-
username and your preview password. This credential is consumed by the gateway
|
|
275
|
-
and is not forwarded to localhost. Application HTTP Basic authentication cannot
|
|
276
|
-
share the same Authorization header, so use an application session cookie or a
|
|
277
|
-
bearer token route without preview password protection. Policy changes and token
|
|
278
|
-
revocations take effect within 30 seconds on connected gateways.
|
|
101
|
+
[Apache-2.0](LICENSE) © 2026 ElemOps
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "portpreview",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"description": "Instant secure previews for localhost apps — expose a local port through a public HTTPS URL.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./lib/index.mjs",
|
|
@@ -35,8 +35,6 @@
|
|
|
35
35
|
"scripts": {
|
|
36
36
|
"prepublishOnly": "npm test",
|
|
37
37
|
"start": "node bin/portpreview.mjs",
|
|
38
|
-
"gateway": "node bin/gateway.mjs",
|
|
39
|
-
"telegram-daemon": "node bin/telegram-daemon.mjs",
|
|
40
38
|
"test": "node --test test/*.test.mjs"
|
|
41
39
|
},
|
|
42
40
|
"keywords": [
|
|
@@ -45,7 +43,10 @@
|
|
|
45
43
|
"preview",
|
|
46
44
|
"webhook",
|
|
47
45
|
"devtools",
|
|
48
|
-
"cli"
|
|
46
|
+
"cli",
|
|
47
|
+
"ngrok",
|
|
48
|
+
"localtunnel",
|
|
49
|
+
"tcp-tunnel"
|
|
49
50
|
],
|
|
50
51
|
"engines": {
|
|
51
52
|
"node": ">=18"
|
|
@@ -60,7 +61,10 @@
|
|
|
60
61
|
"url": "https://github.com/elemops/portpreview/issues"
|
|
61
62
|
},
|
|
62
63
|
"dependencies": {
|
|
63
|
-
"node-telegram-bot-api": "^1.2.0",
|
|
64
64
|
"ws": "^8.19.0"
|
|
65
|
+
},
|
|
66
|
+
"publishConfig": {
|
|
67
|
+
"access": "public",
|
|
68
|
+
"registry": "https://registry.npmjs.org/"
|
|
65
69
|
}
|
|
66
70
|
}
|