Sign inStart free
All articles
Use PortPreview with Next.js for HTTPS tunnels, webhooks, and OAuth
dev stacksNext.jsApp Routerlocal developmentlocalhost tunneling

How to Use PortPreview with a Next.js App

To use PortPreview with a Next.js app, run next dev on port 3000, start npx portpreview 3000, and use the HTTPS URL for OAuth redirects, webhook route handlers, mobile previews, and sharing in-progress UI — no deploy required.

Why tunnel a Next.js app

Next.js is often the public face of a product: marketing pages, dashboards, and API route handlers in one repo. Third parties still cannot reach localhost. A tunnel gives you a stable public HTTPS origin while you iterate in next dev or next dev --turbo.

Quick start

  1. From your Next.js project: npm run dev (default port 3000).
  2. In a second terminal: npx portpreview 3000.
  3. Open the printed https://....portpreview.dev URL in a browser or phone.
  4. Point external services at the same origin plus your API path.

App Router API routes behind a tunnel

Route handlers receive proxied requests with original headers intact — useful for webhook signatures. Keep webhook routes on the Node runtime when providers need Node crypto:

// app/api/health/route.ts
export async function GET() {
  return Response.json({ ok: true });
}

For signature verification, read await request.text() before parsing JSON. Middleware that reads the body globally will break webhooks; exclude /api/webhooks in middleware.ts matcher.

Environment variables and public URLs

When client code must know its public origin (OAuth, absolute asset URLs), store the active tunnel in .env.local:

NEXT_PUBLIC_APP_URL=https://abc123.portpreview.dev

Restart next dev after changing env files. For server-only webhook secrets, use unprefixed vars like STRIPE_WEBHOOK_SECRET.

WebSockets and custom servers

If you run a custom Node server with socket.io alongside Next.js, PortPreview forwards WebSocket upgrades by default. Turbopack does not change tunnel behavior — only the bundler.

Security checklist

  • Do not commit .env.local or tunnel URLs to git.
  • Protect admin and preview routes with auth even on tunnels.
  • Rotate tunnel sessions when sharing widely.
  • Review localhost tunnel security.

Next.js documentation covers route handlers and env loading. Start PortPreview free for Next.js-friendly HTTPS tunnels.

Frequently asked questions

How do I expose a Next.js dev server with PortPreview?
Start your Next.js app on localhost (usually port 3000), then run npx portpreview 3000 in another terminal. Use the HTTPS URL for webhooks, OAuth redirects, and sharing.
Can I test OAuth callbacks on localhost with Next.js?
External providers require a public HTTPS redirect URI. Register your PortPreview tunnel URL as the callback during development instead of http://localhost.
What is the most common Next.js tunneling mistake?
Reading the request body in root middleware or calling request.json() before signature verification breaks webhook routes. Exclude webhook paths and use await request.text() for raw bodies.
Is it safe to share a Next.js tunnel URL?
Treat tunnel URLs like temporary credentials. Share only with trusted collaborators, disable when done, and never expose admin routes without authentication. See localhost tunnel security best practices.