expo-cloudflare-tunnel

Replace @expo/ngrok with cloudflared tunnel for Expo dev builds. Free, no account required.

Prerequisites

You must install cloudflared before using this package.

| Platform | Install | |----------|---------| | npm (any OS) | npm install -g cloudflared | | macOS | brew install cloudflared | | Linux (Debian/Ubuntu) | curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared | | Windows | winget install cloudflare.cloudflared or download from developers.cloudflare.com |

Verify installation:

cloudflared --version

Supported Expo SDK versions

| SDK | Status | |-----|--------| | 54 | Full support (timeout + connection props patched) | | 55 | Full support (timeout + connection props patched) | | 56 | Full support (timeout + connection props patched) | | 57-58 | Should work (timeout patched via regex, connection props patched) |

The @expo/ngrok replacement works with any Expo version. The AsyncNgrok.js patch (timeout + connection props) applies to SDK 54+.

Platform note: Tested on Windows and Linux. macOS is untested — please test and report back if you hit issues.

Install

pnpm add -D expo-cloudflare-tunnel
npx expo-tunnel setup

expo-tunnel setup adds pnpm overrides + tunnel script, then runs pnpm install. Done.

Manual setup (skip setup command)

Add to package.json:

"pnpm": {
  "onlyBuiltDependencies": ["expo-cloudflare-tunnel"],
  "overrides": {
    "@expo/ngrok": "link:./node_modules/expo-cloudflare-tunnel/src/stub"
  }
}

Then run pnpm install.

Usage

pnpm tunnel
# or
npx expo start --tunnel

If the tunnel script isn't in your package.json, add it:

"scripts": {
  "tunnel": "expo start --tunnel"
}

Commands

| Command | Description | |---|---| | setup | One-time pnpm config (adds overrides + build approval + tunnel script) | | start [port] | Start cloudflared tunnel manually (default port: 8081) | | kill | Stop running tunnel | | check | Verify cloudflared is installed | | patch [root] | Legacy — direct @expo/ngrok patching |

How it works

• pnpm: overrides @expo/ngrok resolution to our src/stub/ — survives pnpm install
• npm/yarn: postinstall writes node_modules/@expo/ngrok/ stub directly
• AsyncNgrok.js patch: increases tunnel timeout to 30s (cloudflared is slower than ngrok) and strips ngrok-specific hostname/subdomain logic

Expo calls require('@expo/ngrok') — gets our cloudflared implementation, not ngrok.

Troubleshooting

"cloudflared is not installed" or ENOENT error

Install cloudflared (see Prerequisites above). This package does not bundle the cloudflared binary.

If cloudflared is installed but still not found, it's not in your PATH. Fix per platform:

Windows:

copy C:\Path\To\cloudflared.exe %APPDATA%\npm\cloudflared.exe

macOS:

# If installed via brew, it should already be in PATH
# If manually downloaded:
sudo cp cloudflared /usr/local/bin/cloudflared

Linux:

sudo cp cloudflared /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

Verify it works:

cloudflared --version

Tunnel fails to connect

• Ensure cloudflared is in your PATH
• Try npx expo-tunnel start 8081 manually to see cloudflared output
• Cloudflared quick tunnels require internet access

Expo version mismatch

If you see "AsyncNgrok.js not found", your Expo CLI version may not be in the 54-58 range. The ngrok replacement still works — only the timeout/props patches are skipped.