@ngrok/nextjs 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishan Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @ngrok/nextjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run `next dev` with a public ngrok URL, in one command.
+```
+npx @ngrok/nextjs dev
+```
+
+Built on [`@ngrok/ngrok`](https://www.npmjs.com/package/@ngrok/ngrok), ngrok's official
+JavaScript SDK — a native module, and nothing to install besides this package.
+
+## Setup
+
+1. Sign up at [ngrok.com](https://ngrok.com) and grab an authtoken from
+   [the dashboard](https://dashboard.ngrok.com/authtokens).
+2. Put it in `.env.local` in your Next.js project root:
+   ```
+   NGROK_AUTHTOKEN=your_token_here
+   ```
+3. Run it:
+   ```
+   npx @ngrok/nextjs dev
+   ```
+
+You'll get a public URL bound to your ngrok account's dev domain.
+
+## What it does
+
+- Spawns `next dev` and opens an ngrok tunnel to it as one process, so stopping it
+  (`Ctrl+C`) cleanly tears down both — including `next dev`'s own child processes.
+- Defaults to your account's dev domain (`abc123.ngrok-free.dev`).
+- Syncs the tunnel URL into `.env.local` under `NEXTAUTH_URL` and `NEXT_PUBLIC_APP_URL` by
+  default, so auth libraries and client code pick it up automatically.
+- Prints a QR code so you can open the tunnel on your phone. Disable with `NGROK_QR=false`.
+- Prints a one-time setup checklist on first run per project, reminding you to register the
+  URL with your OAuth/webhook providers.
+
+## Config
+
+Optional `ngrok.config.ts` (or `.js`/`.mjs`) in your project root. 
+
+```ts
+export default {
+  url: "https://your-reserved-domain.ngrok.app", // omit for the account's default dev domain
+  env: { url: ["NEXTAUTH_URL", "NEXT_PUBLIC_APP_URL"] },
+  trafficPolicy: `
+on_http_request:
+  - actions:
+      - type: basic-auth
+        config:
+          credentials:
+            - "user:password123"
+`,
+};
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string?` | Public endpoint URL, with scheme. |
+| `pooling` | `boolean?` | Opt in to ngrok endpoint pooling so multiple endpoints can intentionally share one `url` with load-balanced routing. Required when two endpoints would otherwise collide on the same URL. |
+| `trafficPolicy` | `string?` | A raw [ngrok Traffic Policy](https://ngrok.com/docs/traffic-policy/) document (YAML or JSON) — the mechanism for auth, IP restrictions, header manipulation, webhook verification, and more. |
+| `env.url` | `string[]?` | Which env vars in `.env.local` get this endpoint's URL. |
+| `binding` | `"public" \| "internal" \| "kubernetes"?` | Ingress configuration. |
+| `endpoints` | `EndpointConfig[]?` | multi-endpoint case — front more than one local service from a single command. Supersedes the root-level fields above entirely. Each entry also takes `upstream` (a port number or raw address string) alongside `url`/`pooling`/`trafficPolicy`/`env`/`binding`. |
+
+### Personal overrides
+
+Two ways to override the shared config without editing a committed file:
+
+- `NGROK_DOMAIN` env var (bare domain or full URL)
+- `ngrok.config.local.ts` — same shape as `ngrok.config.ts`, gitignore it
+
+Resolution order: `NGROK_DOMAIN` → `ngrok.config.local.ts` → `ngrok.config.ts` → account
+default dev domain.
+
+### Multiple endpoints
+
+```ts
+export default {
+  endpoints: [
+    { upstream: 3000, url: "https://app.mycompany.ngrok.app" },
+    { upstream: 4000, url: "https://api.mycompany.ngrok.app" },
+  ],
+};
+```
+
+Each endpoint needs its own distinct `url`, or `pooling: true` on every endpoint sharing one.
+
+## Examples
+
+### Use your own domain instead of the default dev domain
+
+Requires a domain reserved on your ngrok account. Three ways to point at it, in order of precedence:
+
+**Env var** — quickest, no file needed:
+```
+NGROK_DOMAIN=myapp.ngrok.app npx @ngrok/nextjs dev
+```
+Or put it in `.env.local`. Accepts a bare domain (auto-prefixed to `https://`) or a full URL.
+
+**`ngrok.config.local.ts`** — gitignored, personal-only, persists across runs without
+re-exporting an env var every time:
+```ts
+export default {
+  url: "https://myapp.ngrok.app",
+};
+```
+
+**`ngrok.config.ts`** — committed, shared with the team. Only makes sense here if the domain
+is meant for whoever's running the tool at the time, not concurrently by multiple people — see
+[Personal overrides](#personal-overrides) for why.
+```ts
+export default {
+  url: "https://myapp.ngrok.app",
+};
+```
+
+### Traffic Policy examples
+
+`trafficPolicy` is a raw [ngrok Traffic Policy](https://ngrok.com/docs/traffic-policy/)
+document (YAML or JSON) in `ngrok.config.ts`, applied to the endpoint as-is. A few common ones:
+
+**Basic auth**:
+```ts
+export default {
+  trafficPolicy: `
+on_http_request:
+  - actions:
+      - type: basic-auth
+        config:
+          credentials:
+            - "user:password123"
+`,
+};
+```
+
+**IP allowlist**:
+```ts
+export default {
+  trafficPolicy: `
+on_http_request:
+  - actions:
+      - type: restrict-ips
+        config:
+          enforce: true
+          allow:
+            - "203.0.113.0/24"
+`,
+};
+```
+
+**Webhook signature verification**:
+```ts
+export default {
+  trafficPolicy: `
+on_http_request:
+  - actions:
+      - type: verify-webhook
+        config:
+          provider: stripe
+          secret: "whsec_..."
+`,
+};
+```
+
+## Requirements
+
+- Node.js 18+
+- An ngrok account and authtoken.
+
+## Development
+
+```
+pnpm install
+pnpm run build   # compiles src/ -> dist/
+pnpm test         # runs the unit test suite
+```
+
+See [`examples/test-app`](examples/test-app) for a working Next.js app to test against, and
+[`DESIGN.md`](DESIGN.md) for the design rationale and everything confirmed empirically along
+the way.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { config as loadDotenv } from "dotenv";
+import qrcode from "qrcode-terminal";
+import { loadConfig } from "./config.js";
+import { syncEnvLocal } from "./env-sync.js";
+import { isFirstRunForProject } from "./first-run.js";
+import { openTunnels } from "./tunnels.js";
+async function main() {
+    const cwd = process.cwd();
+    // .env.local is where NGROK_AUTHTOKEN/NGROK_DOMAIN are expected to live
+    // (see DESIGN.md "Config") — Next.js loads it for the `next dev` child
+    // process automatically, but that doesn't put it in *this* process's env,
+    // so without this, NGROK_AUTHTOKEN silently "isn't found" even when it's
+    // sitting right there in the file. Doesn't override already-exported
+    // shell env vars.
+    loadDotenv({ path: resolve(cwd, ".env.local"), quiet: true });
+    const port = Number(process.env.PORT ?? 3000);
+    const config = await loadConfig(cwd, port);
+    // NGROK_DOMAIN wins over config so a personal reserved domain never has to
+    // be hardcoded into a file — see DESIGN.md "Config" for why that matters
+    // once more than one person shares an ngrok account. Only applies to the
+    // endpoint next dev itself is running on. `url` requires a scheme (see
+    // tunnels.ts) — default to https:// if the env var is a bare domain.
+    if (process.env.NGROK_DOMAIN) {
+        const primaryEntry = config.endpoints.find((e) => e.upstream === port);
+        if (primaryEntry) {
+            primaryEntry.url = process.env.NGROK_DOMAIN.includes("://")
+                ? process.env.NGROK_DOMAIN
+                : `https://${process.env.NGROK_DOMAIN}`;
+        }
+    }
+    if (!process.env.NGROK_AUTHTOKEN) {
+        console.error("\nNo NGROK_AUTHTOKEN found.\n" +
+            "Get a free one at https://dashboard.ngrok.com/authtokens, then run:\n" +
+            "  NGROK_AUTHTOKEN=<token> npx @ngrok/nextjs dev\n");
+        process.exit(1);
+    }
+    const next = spawn("npx", ["next", "dev", "--port", String(port)], {
+        stdio: "inherit",
+        shell: process.platform === "win32",
+        detached: process.platform !== "win32",
+    });
+    const killNext = () => {
+        if (next.exitCode !== null || next.pid === undefined)
+            return;
+        if (process.platform === "win32") {
+            spawn("taskkill", ["/pid", String(next.pid), "/T", "/F"]);
+        }
+        else {
+            // next dev spawns its own child processes (Turbopack workers, etc.);
+            // killing just `next.pid` leaves those running and holding the port.
+            // The negative pid targets the whole process group instead.
+            try {
+                process.kill(-next.pid, "SIGTERM");
+            }
+            catch {
+                // group may already be gone
+            }
+        }
+    };
+    let tunnels;
+    try {
+        tunnels = await openTunnels(config.endpoints);
+    }
+    catch (err) {
+        // next dev is already running at this point — if the tunnel setup fails
+        // (e.g. bad config, domain collision), it must not be left orphaned.
+        killNext();
+        throw err;
+    }
+    for (const endpoint of tunnels.endpoints) {
+        console.log(`\n  Public (${endpoint.upstream}): ${endpoint.url}\n`);
+        syncEnvLocal(cwd, endpoint.envVars, endpoint.url);
+    }
+    // QR code only for the primary endpoint (the one next dev is actually
+    // running on) — printing one per endpoint would just be noise. Only
+    // matches when upstream is the plain port number next dev runs on; if the
+    // primary entry's upstream is written as a string instead, it won't be
+    // detected as primary — an accepted edge case, not worth parsing for.
+    const primary = tunnels.endpoints.find((e) => e.upstream === port) ?? tunnels.endpoints[0];
+    if (primary && process.env.NGROK_QR !== "false") {
+        qrcode.generate(primary.url, { small: true });
+    }
+    if (primary && isFirstRunForProject(cwd)) {
+        console.log("  First run for this project — register these URLs once with your OAuth/webhook\n" +
+            "  providers. They won't change again as long as you keep using these domains:\n" +
+            tunnels.endpoints.map((e) => `    ${e.url}`).join("\n") +
+            "\n");
+    }
+    const shutdown = async () => {
+        await tunnels.close();
+        killNext();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    next.on("exit", (code) => {
+        tunnels.close().finally(() => process.exit(code ?? 0));
+    });
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+export interface HttpEndpointOptions {
+    url?: string;
+    pooling?: boolean;
+    trafficPolicy?: string;
+    binding?: "public" | "internal" | "kubernetes";
+}
+export interface EndpointConfig extends HttpEndpointOptions {
+    upstream: number | string;
+    env?: {
+        url?: string[];
+    };
+}
+export interface NgrokNextConfig extends HttpEndpointOptions {
+    env?: {
+        url?: string[];
+    };
+    endpoints?: EndpointConfig[];
+}
+interface ResolvedConfig {
+    endpoints: EndpointConfig[];
+}
+export declare function loadConfig(cwd: string, defaultPort: number): Promise<ResolvedConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createJiti } from "jiti";
+// Only applied to the synthesized single-endpoint case (no explicit
+// `endpoints` array in the user's config) — a user-specified multi-endpoint
+// entry that omits `env` stays un-synced on purpose, since e.g. a secondary
+// API-server endpoint usually shouldn't claim NEXTAUTH_URL.
+const DEFAULT_ENV_VARS = ["NEXTAUTH_URL", "NEXT_PUBLIC_APP_URL"];
+// Checked in this order: personal override first, then shared/committed config.
+// See DESIGN.md "Config" — ngrok.config.local.ts must never be committed.
+const CONFIG_FILENAMES = [
+    "ngrok.config.local.ts",
+    "ngrok.config.local.js",
+    "ngrok.config.local.mjs",
+    "ngrok.config.ts",
+    "ngrok.config.js",
+    "ngrok.config.mjs",
+];
+export async function loadConfig(cwd, defaultPort) {
+    const jiti = createJiti(import.meta.url);
+    for (const filename of CONFIG_FILENAMES) {
+        const path = resolve(cwd, filename);
+        if (!existsSync(path))
+            continue;
+        const config = (await jiti.import(path, { default: true }));
+        const { env, endpoints, ...httpOptions } = config;
+        return {
+            endpoints: endpoints ?? [
+                { upstream: defaultPort, env: { url: env?.url ?? DEFAULT_ENV_VARS }, ...httpOptions },
+            ],
+        };
+    }
+    return { endpoints: [{ upstream: defaultPort, env: { url: DEFAULT_ENV_VARS } }] };
+}

package/dist/env-sync.d.ts

@@ -0,0 +1 @@
+export declare function syncEnvLocal(cwd: string, keys: string[], url: string): void;

package/dist/env-sync.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+// Updates (or appends) the given keys in .env.local with the tunnel URL,
+// preserving every other line in the file untouched.
+export function syncEnvLocal(cwd, keys, url) {
+    if (keys.length === 0)
+        return;
+    const path = resolve(cwd, ".env.local");
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const lines = existing.length > 0 ? existing.split("\n") : [];
+    const seen = new Set();
+    const updated = lines.map((line) => {
+        const match = line.match(/^([A-Za-z0-9_]+)=/);
+        if (match && keys.includes(match[1])) {
+            seen.add(match[1]);
+            return `${match[1]}=${url}`;
+        }
+        return line;
+    });
+    for (const key of keys) {
+        if (!seen.has(key))
+            updated.push(`${key}=${url}`);
+    }
+    const output = updated.join("\n").replace(/\n*$/, "\n");
+    writeFileSync(path, output);
+}

package/dist/first-run.d.ts

@@ -0,0 +1 @@
+export declare function isFirstRunForProject(cwd: string): boolean;

package/dist/first-run.js

@@ -0,0 +1,15 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+// Marker lives under node_modules so it never needs its own gitignore entry —
+// node_modules is already universally ignored.
+function markerPath(cwd) {
+    return resolve(cwd, "node_modules/.cache/ngrok-nextjs/first-run");
+}
+export function isFirstRunForProject(cwd) {
+    const path = markerPath(cwd);
+    if (existsSync(path))
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, "");
+    return true;
+}

package/dist/tunnels.d.ts

@@ -0,0 +1,27 @@
+import type { EndpointConfig } from "./config.js";
+export interface OpenedEndpoint {
+    upstream: number | string;
+    url: string;
+    envVars: string[];
+}
+export interface Tunnels {
+    endpoints: OpenedEndpoint[];
+    close(): Promise<void>;
+}
+export type ParsedEndpoint = {
+    kind: "default";
+} | {
+    kind: "http";
+    hostname: string;
+    scheme: "HTTP" | "HTTPS";
+} | {
+    kind: "tls";
+    hostname: string;
+} | {
+    kind: "tcp";
+    remoteAddr: string;
+};
+export declare function parseEndpointUrl(url: string | undefined): ParsedEndpoint;
+export declare function forwardAddr(upstream: number | string): string;
+export declare function validateUrlGroups(endpoints: EndpointConfig[]): void;
+export declare function openTunnels(endpoints: EndpointConfig[]): Promise<Tunnels>;

package/dist/tunnels.js

@@ -0,0 +1,101 @@
+import ngrok from "@ngrok/ngrok";
+// Pure — no SDK calls — so the scheme-inference rules can be unit tested
+// without a live session. The endpoint type (HTTP/TCP/TLS) and its
+// domain-equivalent setting aren't separate config fields — both come from
+// `url`'s own scheme, since that's already how everyone writes URLs.
+export function parseEndpointUrl(url) {
+    if (!url)
+        return { kind: "default" };
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Endpoint url "${url}" must include a scheme (http://, https://, tcp://, or ` +
+            "tls://) so the endpoint type and domain can be inferred from it.");
+    }
+    const proto = parsed.protocol.replace(":", "");
+    switch (proto) {
+        case "http":
+        case "https":
+            return { kind: "http", hostname: parsed.hostname, scheme: proto.toUpperCase() };
+        case "tls":
+            return { kind: "tls", hostname: parsed.hostname };
+        case "tcp":
+            // TCP addresses are host:port, not a bare domain — e.g. "2.tcp.ngrok.io:21746".
+            return { kind: "tcp", remoteAddr: parsed.host };
+        default:
+            throw new Error(`Endpoint url "${url}" has unsupported proto "${proto}:" — expected http, https, tcp, or tls.`);
+    }
+}
+// tcp/tls are genuinely different SDK builders from http, with different
+// address-setting methods — this is the only place that matters.
+function buildListener(session, entry) {
+    const parsed = parseEndpointUrl(entry.url);
+    const builder = parsed.kind === "default"
+        ? session.httpEndpoint()
+        : parsed.kind === "http"
+            ? session.httpEndpoint().domain(parsed.hostname).scheme(parsed.scheme)
+            : parsed.kind === "tls"
+                ? session.tlsEndpoint().domain(parsed.hostname)
+                : session.tcpEndpoint().remoteAddr(parsed.remoteAddr);
+    if (entry.pooling)
+        builder.poolingEnabled(true);
+    if (entry.trafficPolicy)
+        builder.trafficPolicy(entry.trafficPolicy);
+    if (entry.binding)
+        builder.binding(entry.binding);
+    return builder;
+}
+export function forwardAddr(upstream) {
+    return typeof upstream === "number" ? `http://localhost:${upstream}` : upstream;
+}
+// ngrok does not reject or warn when two listeners in the same session end
+// up on the same public url — it silently lets the most recently opened
+// listener win, and the other becomes unreachable with zero indication of
+// why. Confirmed empirically, isolated from this wrapper's own code (a raw
+// SDK script showed both listenAndForward() calls resolving successfully
+// with identical URLs, no exception either time). An endpoint with no
+// explicit `url` falls back to the account's default dev domain, so two
+// url-less endpoints collide there just as surely as two hardcoding the
+// same string. Either case is fine *if* every endpoint sharing that url
+// opts into `pooling: true` (ngrok's real mechanism for intentionally
+// sharing an endpoint with load-balanced routing, confirmed live — repeated
+// requests alternated between two different local backends) — otherwise
+// it's the silent-failure footgun, so fail fast instead.
+export function validateUrlGroups(endpoints) {
+    const groups = new Map();
+    for (const entry of endpoints) {
+        const key = entry.url ?? "";
+        groups.set(key, [...(groups.get(key) ?? []), entry]);
+    }
+    for (const [url, group] of groups) {
+        if (group.length <= 1)
+            continue;
+        if (group.every((e) => e.pooling))
+            continue;
+        const label = url || "the account's default dev domain";
+        const upstreams = group.map((e) => e.upstream).join(", ");
+        throw new Error(`Upstreams ${upstreams} would all share ${label}. Without endpoint pooling, only the ` +
+            "most recently opened listener actually receives traffic — the rest go silently " +
+            'unreachable. Set "pooling: true" on each of these endpoints to share it ' +
+            "intentionally, or give each its own url.");
+    }
+}
+// Always goes through a single explicit Session, even for the common
+// one-endpoint case — this is what lets every option apply uniformly
+// regardless of how many endpoints are configured or what proto each uses.
+export async function openTunnels(endpoints) {
+    validateUrlGroups(endpoints);
+    const session = await new ngrok.SessionBuilder().authtokenFromEnv().connect();
+    const opened = [];
+    for (const entry of endpoints) {
+        const builder = buildListener(session, entry);
+        const listener = await builder.listenAndForward(forwardAddr(entry.upstream));
+        const url = listener.url();
+        if (!url)
+            throw new Error(`ngrok listener for upstream ${entry.upstream} returned no URL`);
+        opened.push({ upstream: entry.upstream, url, envVars: entry.env?.url ?? [] });
+    }
+    return { endpoints: opened, close: () => session.close() };
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@ngrok/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Run next dev with a public ngrok URL, no separate binary or config required.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ngrok-nextjs": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepare": "npm run build",
+    "test": "tsc -p tsconfig.test.json && node --test 'dist-test/**/*.test.js'"
+  },
+  "dependencies": {
+    "@ngrok/ngrok": "^1.7.0",
+    "dotenv": "17.4.2",
+    "jiti": "2.7.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "@types/qrcode-terminal": "^0.12.2",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}