Test Localhost on Your Phone
Why localhost does not work on your phone
When you run npm run dev, your app listens on localhost (127.0.0.1) — a loopback address that only exists on your laptop. Your phone is a separate device, often on a different network. Typing localhost:5173 on your phone opens the phone's own loopback, not your laptop.
You need a public HTTPS URL that forwards to your dev server. A development tunnel creates that bridge. LocalToLink also prints a QR code in the terminal so you can scan and open the URL instantly.
Quick workflow
1. Start your dev server:
npm run dev
2. Start LocalToLink:
npx localtolink --port 5173
3. Scan the QR code printed in the terminal with your phone camera (iOS/Android).
4. Tap the notification to open your app in the mobile browser.
The public URL looks like https://k7m2x9p4q1.localtolink.com. Anyone with the URL can access your dev server while the tunnel runs.
Disable QR code output
For CI, headless servers, or screen recordings where the QR art is distracting:
npx localtolink --port 5173 --no-qr
The public URL is still printed as text — share it manually via Slack, email, or messaging apps.
Browser interstitial on mobile
When the visitor interstitial policy is enabled, the first time you open the tunnel URL in a mobile browser you may see Opening a shared link. Tap Continue once per subdomain (remembered for 24 hours). If you restart the tunnel and get a new subdomain, repeat on the new URL.
Testing checklist for mobile
| Check | Why it matters |
|---|---|
| Responsive layout | Test portrait and landscape orientations |
| Touch interactions | Hover states do not exist on mobile |
| API calls use tunnel URL | Hardcoded localhost in frontend code fails on phone |
| Font and image loading | Confirm assets load over HTTPS through tunnel |
| Form inputs and keyboards | Virtual keyboard can resize viewport |
| Performance on real network | Wi-Fi vs cellular behave differently |
Ensure your dev server is reachable
Most frameworks bind to localhost or 0.0.0.0 by default, which works with LocalToLink. If your server binds to a specific interface only, confirm it accepts connections on the port LocalToLink forwards to.
Vite — usually works out of the box, but HMR may need config. See Vite HMR Through a Tunnel.
Next.js — Next.js 15.2+ requires allowedDevOrigins. See Next.js Dev Server Through a Tunnel.
Framework-specific notes
Vite / React / Vue
Hot Module Replacement (HMR) uses WebSockets. Configure Vite for tunnel access:
// vite.config.js
export default defineConfig({
server: {
allowedHosts: [".localtolink.com"],
hmr: { clientPort: 443, protocol: "wss" },
},
});
Full details in Vite HMR Through a Tunnel.
Next.js
Add to next.config.js:
const nextConfig = {
allowedDevOrigins: ["*.localtolink.com"],
};
export default nextConfig;
See Next.js Dev Server Through a Tunnel.
API routes and fetch calls
If your frontend calls fetch("http://localhost:3000/api/..."), those requests fail on your phone. Use relative URLs (/api/...) or environment variables that resolve to the tunnel origin when accessed through the tunnel URL.
Session limits for mobile testing
| Limit | Impact |
|---|---|
| 2 hours | Restart tunnel for long testing sessions |
| 1 GB bandwidth | Sufficient for UI and API testing |
| Random subdomain | Bookmark the new URL after each session |
| 20 concurrent connections | Fine for personal device testing |
Troubleshooting
| Problem | Fix |
|---|---|
| QR scan opens wrong page | Confirm tunnel is still running; URL may have expired |
| Page loads but API calls fail | Replace hardcoded localhost with relative URLs |
| HMR does not work on phone | Configure Vite/Next.js WebSocket settings |
| Warning page every time | New subdomain each session — tap through once per subdomain |
| Slow loading on cellular | Expected; tunnel adds latency vs local Wi-Fi |
| Tunnel limit message | Only one tunnel per IP on free tier — stop other tunnels |
Testing OAuth on mobile
OAuth flows on mobile require HTTPS redirect URIs. Register the tunnel URL in your provider's console. See OAuth Callback on Localhost.
FAQ
Does my phone need to be on the same Wi-Fi?
No. The tunnel URL works from any network — cellular, office Wi-Fi, or home.
Can I test on multiple phones?
Yes. Share the same public URL. Up to 20 concurrent connections on the free tier.
Is the QR code secure?
The QR encodes the same public URL printed in text. Anyone with the URL can access your dev server while the tunnel runs. Do not share tunnel URLs publicly if your app exposes sensitive data.
Can I test native apps (not browser)?
Yes, if the app can be configured to hit the tunnel URL as its API base. Deep links for OAuth require registering the tunnel callback URL.
See Expose Localhost to the Internet for tunnel basics.
Try it now
Start a tunnel from your project directory — no account required.
$ npx --yes localtolink@latest