|
| 1 | +--- |
| 2 | +title: Jump |
| 3 | +order: 55 |
| 4 | +--- |
| 5 | + |
| 6 | +[Jump](https://bifrost.nativephp.com/jump) is a companion mobile app that lets you preview your NativePHP app on a real |
| 7 | +device without ever opening Xcode or Android Studio. You write code on your machine; Jump renders it on your phone. |
| 8 | + |
| 9 | +Combined with the `native:jump` Artisan command, it gives you a fast, hot-reloading development loop that works on both |
| 10 | +iOS and Android with a single command. |
| 11 | + |
| 12 | +## How it works |
| 13 | + |
| 14 | +When you run `native:jump`, NativePHP starts three things on your machine: |
| 15 | + |
| 16 | +- **A PHP dev server** that serves a QR code page and proxies HTTP requests through to your Laravel app |
| 17 | +- **An `artisan serve` process** running your Laravel application (unless you opt out — see [Bring your own server](#bring-your-own-server)) |
| 18 | +- **A WebSocket bridge** that the Jump app on your phone connects to, used to invoke native APIs and to deliver Vite |
| 19 | + HMR updates |
| 20 | + |
| 21 | +When you scan the QR code with the Jump app, your phone connects back to your machine over Wi-Fi and starts rendering |
| 22 | +your Laravel app inside Jump's WebView. Calls to NativePHP APIs (e.g. `Camera::open()`) are sent over the bridge to the |
| 23 | +device, executed natively, and the result is sent back to PHP — exactly as it would behave in a packaged build. |
| 24 | + |
| 25 | +## Quick start |
| 26 | + |
| 27 | +1. Install Jump on your device from the |
| 28 | + [App Store](https://apps.apple.com/us/app/bifrost-jump/id6757173334) or |
| 29 | + [Google Play](https://play.google.com/store/apps/details?id=com.bifrosttech.jump). You'll need **Jump v2 or |
| 30 | + later** to work with NativePHP Mobile v3.3. |
| 31 | +2. Make sure your phone and your computer are on the same Wi-Fi network. |
| 32 | +3. From your Laravel project, run: |
| 33 | + |
| 34 | +```shell |
| 35 | +php artisan native:jump |
| 36 | +``` |
| 37 | + |
| 38 | +4. Scan the QR code shown in your terminal with the Jump app. |
| 39 | + |
| 40 | +Your app will load on your device. Any changes you make to Blade views, Livewire components or your CSS/JS bundle will |
| 41 | +reload automatically. |
| 42 | + |
| 43 | +<aside> |
| 44 | + |
| 45 | +#### New to NativePHP? |
| 46 | + |
| 47 | +If you're just starting out, the [Quick Start](/docs/mobile/3/getting-started/quick-start) walks you through installing |
| 48 | +NativePHP and running Jump for the first time. |
| 49 | + |
| 50 | +</aside> |
| 51 | + |
| 52 | +## Network requirements |
| 53 | + |
| 54 | +Jump connects from your phone to your computer over your local network. For this to work: |
| 55 | + |
| 56 | +- Both devices need to be on the **same Wi-Fi network** (or one device tethered to the other) |
| 57 | +- Your firewall must allow inbound connections to the HTTP, WebSocket, bridge and Vite proxy ports (defaults: `3000`, |
| 58 | + `3001`, `3002`, `3003`) |
| 59 | +- If you're on a public/guest network that isolates clients from each other, Jump won't be able to connect — switch to a |
| 60 | + private network or use a personal hotspot |
| 61 | + |
| 62 | +NativePHP also advertises the dev server via mDNS so the Jump app can discover it automatically. If your network blocks |
| 63 | +multicast traffic, you can disable this with `--no-mdns` and scan the QR code instead. |
| 64 | + |
| 65 | +## Hot reload |
| 66 | + |
| 67 | +Jump uses Vite's HMR pipeline. When you run `npm run dev` alongside `native:jump`, the dev server's HMR WebSocket is |
| 68 | +proxied through Jump's own port (`3003` by default) so your phone can subscribe to updates without you having to |
| 69 | +reconfigure `vite.config.js` for network access. |
| 70 | + |
| 71 | +You don't need to do anything special — just start Vite the way you normally would and Jump will pick it up. |
| 72 | + |
| 73 | +## The Bridge |
| 74 | + |
| 75 | +In a normal mobile build, calls like `Camera::open()` execute in-process on the device. With Jump, PHP runs on your |
| 76 | +machine but the native APIs still live on the phone. NativePHP makes this transparent: when Jump is active, the |
| 77 | +`nativephp_call()` function dials the bridge port over TCP, the WebSocket server relays the call to the connected |
| 78 | +device, and the device replies with the result. |
| 79 | + |
| 80 | +This means you can develop and test the vast majority of native functionality — sensors, dialogs, camera, biometrics, |
| 81 | +file pickers and more — without ever building the app. |
| 82 | + |
| 83 | +<aside> |
| 84 | + |
| 85 | +A few APIs that depend on long-running state on the device (e.g. background tasks) behave best in a packaged build. For |
| 86 | +day-to-day development everything else "just works". |
| 87 | + |
| 88 | +</aside> |
| 89 | + |
| 90 | +### Bridge logs |
| 91 | + |
| 92 | +The bridge writes to `storage/logs/jump-bridge.log`. You can tail it to watch native calls in real time: |
| 93 | + |
| 94 | +```shell |
| 95 | +tail -f storage/logs/jump-bridge.log |
| 96 | +``` |
| 97 | + |
| 98 | +The path is also printed under **Bridge log** in the `native:jump` terminal output. |
| 99 | + |
| 100 | +## Configuration |
| 101 | + |
| 102 | +The dev server is configured under the `server` key in your `config/nativephp.php` file: |
| 103 | + |
| 104 | +```php |
| 105 | +'server' => [ |
| 106 | + 'http_port' => env('NATIVEPHP_HTTP_PORT', 3000), |
| 107 | + 'ws_port' => env('NATIVEPHP_WS_PORT', 8081), |
| 108 | + 'service_name' => env('NATIVEPHP_SERVICE_NAME', 'NativePHP Server'), |
| 109 | + 'open_browser' => env('NATIVEPHP_OPEN_BROWSER', true), |
| 110 | +], |
| 111 | +``` |
| 112 | + |
| 113 | +See [Configuration](/docs/mobile/3/getting-started/configuration#development-server) for the full reference. |
| 114 | + |
| 115 | +Per-run options (ports, host, IP, mDNS) can all be overridden on the command line — see the |
| 116 | +[`native:jump` command reference](/docs/mobile/3/getting-started/commands#nativejump) for the full list of flags. |
| 117 | + |
| 118 | +### Multiple network interfaces |
| 119 | + |
| 120 | +If your machine has more than one IP address (e.g. Wi-Fi and Ethernet, or a VPN is active), `native:jump` will prompt |
| 121 | +you to choose which one to advertise in the QR code. Pick the IP that your phone can actually reach — usually the Wi-Fi |
| 122 | +one. |
| 123 | + |
| 124 | +You can also pre-select it with `--ip=`: |
| 125 | + |
| 126 | +```shell |
| 127 | +php artisan native:jump --ip=192.168.1.42 |
| 128 | +``` |
| 129 | + |
| 130 | +### Bring your own server |
| 131 | + |
| 132 | +By default `native:jump` starts an `artisan serve` for you. If you're already running your own server (for example |
| 133 | +[Herd](https://herd.laravel.com), Valet, Sail, or `php artisan serve` in another tab), pass `--no-serve` and tell Jump |
| 134 | +which port your server is on: |
| 135 | + |
| 136 | +```shell |
| 137 | +php artisan native:jump --no-serve --laravel-port=8000 |
| 138 | +``` |
| 139 | + |
| 140 | +You'll also need to export the bridge port when starting your own server, so that `nativephp_call()` inside Laravel |
| 141 | +dials the right TCP port. `native:jump` prints the exact command to copy: |
| 142 | + |
| 143 | +```shell |
| 144 | +JUMP_BRIDGE_PORT=3002 php artisan serve --port=8000 |
| 145 | +``` |
| 146 | + |
| 147 | +### Custom ports |
| 148 | + |
| 149 | +If something else on your machine is already using a port, NativePHP will automatically find the next available one and |
| 150 | +print a message. If you want to pin the ports yourself, all of them can be set explicitly: |
| 151 | + |
| 152 | +```shell |
| 153 | +php artisan native:jump \ |
| 154 | + --http-port=3000 \ |
| 155 | + --ws-port=3001 \ |
| 156 | + --bridge-port=3002 \ |
| 157 | + --vite-proxy-port=3003 \ |
| 158 | + --laravel-port=8000 |
| 159 | +``` |
| 160 | + |
| 161 | +## Stopping the server |
| 162 | + |
| 163 | +Press `Ctrl+C` in the terminal where `native:jump` is running. NativePHP will shut down the bridge, the PHP server and |
| 164 | +the managed `artisan serve` process cleanly. |
| 165 | + |
| 166 | +## When to use Jump vs `native:run` |
| 167 | + |
| 168 | +| Use Jump when... | Use `native:run` when... | |
| 169 | +|------------------|--------------------------| |
| 170 | +| You want the fastest possible iteration loop | You need to test a packaged build | |
| 171 | +| You don't have Xcode or Android Studio installed | You're testing release/bundle builds for store submission | |
| 172 | +| You're _not_ working on a Mac or don't have an Apple Developer account but want to test on a real iOS device | You're testing native code in plugins you're authoring | |
| 173 | +| You want to share a preview with a teammate over the same network | You need to test app start-up behaviour or bundled assets | |
| 174 | + |
| 175 | +For most day-to-day development, Jump is the fastest way to see changes on a real device. Once you're ready to ship, |
| 176 | +use [`native:package`](/docs/mobile/3/getting-started/commands#nativepackage) to build a signed binary. |
0 commit comments