Originally published on php-apps.learnio.dev — part of the Using Native PHP course. View this lesson on the original site.

Chapter project: your first screen on mobile

This is the Chapter 1 capstone. By the end you will have a Laravel app running on your phone through Jump, showing a simple custom index page — not the default Laravel welcome screen.

You have already scaffolded Laravel (lesson 1.6) and learned the dev loop (lesson 1.7). This lesson puts those pieces together in order. Follow every step; skip none.

Solution on GitHub

Work through the steps below in your own Laravel project, or clone the reference solution and compare file for file:

Click here to see the GitHub solution

You can also open the same folder with the View Code Example button on this lesson page.

git clone https://github.com/stuarttodd-dev/halfshellstudios-academy.git
cd halfshellstudios-academy/using-native-php/1-introduction-and-mobile-architecture/chapter-project-first-mobile-screen
chmod +x setup.sh && ./setup.sh
php artisan native:install
php artisan native:jump

What you are building

A single route (/) that renders a mobile-friendly Blade view with a heading and a short confirmation message. Nothing else — no auth, no database, no plugins. The point is to prove the full path from Laravel on your machine to pixels on your phone.

Before you start

Confirm you have:

  • A Laravel app that loads in the browser (from lesson 1.6)
  • PHP 8.3+, Composer, and Node.js installed
  • The Jump app on your phone — bifrost.nativephp.com/jump
  • Phone and laptop on the same Wi-Fi network

Work from your project root for every command below. Replace my-app with your folder name if different.

Step 1: Add NativePHP to your Laravel project

cd my-app
composer require nativephp/mobile

Add your app identifier to .env before running the installer:

NATIVEPHP_APP_ID=com.yourcompany.myapp

Run the NativePHP installer:

php artisan native:install

Add nativephp/ to .gitignore if it is not already there — that directory is regenerated by the installer.

Step 2: Create a basic mobile index page

Replace the default welcome screen with a simple page you can recognise on your phone.

Open routes/web.php and make sure the home route points at a named view:

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('mobile-home');
});

Create resources/views/mobile-home.blade.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>My NativePHP App</title>
    <style>
        * { box-sizing: border-box; margin: 0; padding: 0; }
        body {
            font-family: system-ui, sans-serif;
            min-height: 100vh;
            display: flex;
            align-items: center;
            justify-content: center;
            background: #0f172a;
            color: #e2e8f0;
            padding: 1.5rem;
        }
        main {
            text-align: center;
            max-width: 24rem;
        }
        h1 { font-size: 1.75rem; margin-bottom: 0.75rem; }
        p { color: #94a3b8; line-height: 1.5; }
    </style>
</head>
<body>
    <main>
        <h1>It works on mobile</h1>
        <p>This page is served from Laravel and rendered on your phone through NativePHP Jump.</p>
    </main>
</body>
</html>

Check it in the browser before touching your phone:

php artisan serve

Open http://127.0.0.1:8000 and confirm you see "It works on mobile". Stop the server with Ctrl+C when done — Jump will start its own server in the next step (unless you use --no-serve).

Step 3: Install Jump on your phone

If you have not already:

  1. Install Jump from bifrost.nativephp.com/jump.
  2. Connect your phone and laptop to the same Wi-Fi network.
  3. Disable VPN on either device if Jump fails to connect.

Step 4: Run Jump and scan the QR code

From your project root:

php artisan native:jump

A QR code appears in the terminal. Open Jump on your phone, scan it, and wait for the app to load.

If you prefer to keep php artisan serve running in another terminal:

php artisan native:jump --no-serve --laravel-port=8000

If your machine has multiple network interfaces (Wi-Fi plus Ethernet, or an active VPN), Jump may ask which IP to advertise. Pick the address your phone can reach — usually your Wi-Fi LAN IP. You can also set it explicitly:

php artisan native:jump --ip=192.168.1.42

Optional: for live CSS and JS reload while Jump is running, start Vite in a second terminal:

npm run dev

flowchart TD
    A[Laravel app with mobile-home view] --> B[composer require nativephp/mobile]
    B --> C[native:install + NATIVEPHP_APP_ID]
    C --> D[Verify in browser]
    D --> E[Install Jump on phone]
    E --> F[Same Wi-Fi]
    F --> G[php artisan native:jump]
    G --> H[Scan QR code]
    H --> I[Custom index page on device]

Step 5: Confirm success

You are done when all of these are true:

  1. Jump connects without a network error.
  2. Your phone shows the dark page with "It works on mobile" — not the default Laravel welcome art.
  3. Editing the <h1> text in mobile-home.blade.php, saving, and refreshing (or relying on HMR with npm run dev) updates what you see on the phone.

Take a screenshot if you like — you have just run PHP on a mobile device.

If it goes wrong

Symptom What to try
Jump cannot connect Same Wi-Fi on both devices; turn off VPN; try --ip=YOUR_LAN_IP
Blank screen after scan Run php artisan key:generate; check storage/logs/laravel.log
Still see Laravel welcome page Confirm routes/web.php returns view('mobile-home') and the Blade file exists
Port already in use Stop other artisan serve processes or pass --laravel-port= matching your running server
native:install fails Ensure NATIVEPHP_APP_ID is set in .env before installing

For platform-specific setup (Xcode, Android Studio, firewall rules), see Chapter 2.

Solution on GitHub (reference)

Full project with mobile-home view, NativePHP config, and setup script:

Click here to see the GitHub solution

Remember

Browser first, phone second. Get the page right at http://127.0.0.1:8000, then prove the same Laravel code on device through Jump. Everything else in this course builds on that loop.

From Using Native PHP — Introduction and first screen on mobile