Mobile release 2025-12-05 (#243)

Author: simonhamp

resources/views/docs/mobile/2/concepts/authentication.md

@@ -74,18 +74,34 @@ You will likely want to use an OAuth client library in your app to make interact
 When initiating the auth flow for the user, you should use the `Native\Mobile\Facades\Browser::auth()` API, as this is
 purpose-built for securely passing authorization codes back from the OAuth service to your app.
 
-You should set your redirect URL to `nativephp://127.0.0.1/some/route`, where `some/route` is a route you've defined in
-your app's routes that will be able to handle the auth code.
+For this to work, you must set a `NATIVEPHP_DEEPLINK_SCHEME` that will be unique for your application on users' devices.
 
-Note that the scheme of the redirect URL in this case is **always** `nativephp://`. This has nothing to do with any
-custom deep link scheme you may have set for your app. It is only tied to the `Browser::auth()` session.
+```dotenv
+NATIVEPHP_DEEPLINK_SCHEME=myapp
+```
+
+Then you must define your redirect URL. It should match your scheme and the route in your app that will handle the callback
+data.
+
+```php
+Browser::auth('https://workos.com/my-company/auth?redirect=myapp://auth/handle')
+```
+
+Most services will expect you to pre-define your redirect URLs as a security feature. You should be able to provide your
+exact URL, as this will be the most secure method.
+
+How you handle the response in your app depends on how that particular API operates and the needs of your application.
 
 <aside>
 
-Make sure you have good security around your auth service's authentication endpoint. As it will be accessed from many
-devices via an API, standard browser security such as CSRF protections will not be available to you.
+#### Security
+
+If you're running your own auth service, make sure you have good security around its authentication endpoint. As it
+will be accessed by unauthenticated from many devices via an API, standard browser security — such as CSRF protection —
+**will not be available** to you.
 
-Ensure you have appropriate rate limiting in place and even consider using an authentication key that you distribute
-with your apps. These steps will all help defend the endpoint against abuse.
+Ensure you have appropriate **rate limiting** in place and even consider using an **authentication key** that you
+distribute with your apps and is solely used to for accessing the authentication endpoint. These steps will all help
+defend the endpoint against abuse.
 
 </aside>

resources/views/docs/mobile/2/getting-started/development.md

@@ -99,10 +99,42 @@ If you're familiar with these tools, you can easily open the projects using the
 php artisan native:open
 ```
 
+### Configuration
+
+You can configure the folders that the `watch` command pays attention to in your `config/nativephp.php` file:
+
+```php
+'hot_reload' => [
+    'watch_paths' => [
+        'app',
+        'routes',
+        'config',
+        'database',
+        // Make sure "public" is listed in your config [tl! highlight:1]
+        'public',  
+    ],
+]
+```
+
+<aside>
+
+#### Skip the prompts
+
+If you are tired of prompts, you can run most commands - like `native:run` - with arguments and options that allow you
+to skip various prompts. Use the `--help` flag on a command to find out what values you can pass directly to it:
+
+```shell
+php artisan native:run --help
+```
+
+</aside>
+
+
 ## Hot Reloading
 
 We've tried to make compiling your apps as fast as possible, but when coming from the 'make a change; hit refresh'-world
-of PHP development that we all love, compiling apps can feel like a slow and time-consuming process.
+of typical browser-based PHP development that we all love, compiling apps can feel like a slow and time-consuming
+process.
 
 Hot reloading aims to make your app development experience feel just like home.
 
@@ -112,69 +144,73 @@ You can start hot reloading by running the following command:
 php artisan native:watch
 ```
 
-You can also pass the `--watch` option to the `native:run` command.
+<aside>
+
+#### 🔥 Hot Tip!
+
+You can also pass the `--watch` option to the `native:run` command. This will build and deploy a fresh version of your
+application to the target device and _then_ start the watcher, all in one go.
+
+</aside>
 
 This will start a long-lived process that watches your application's source files for changes, pushing them into the
 emulator after any updates and reloading the current screen.
 
-Use this in tandem with Vite's own HMR for the platform you wish to test on:
+If you're using Vite, we'll also use your Node CLI tool of choice (`npm`, `bun`, `pnpm`, or `yarn`) to run Vite's HMR
+server.
 
-```shell
-npm run dev -- --mode=ios
+### Enabling HMR
 
-npm run dev -- --mode=android
-```
+To make HMR work, you'll need to add the `hot` file helper to your `laravel` plugin's config in your `vite.config.js`:
 
-This is useful during development for quickly testing changes without re-compiling your entire app. When you make
-changes to any files in your Laravel app, the web view will be reloaded and your changes should show almost immediately.
+```js
+import { nativephpMobile, nativephpHotFile } from './vendor/nativephp/mobile/resources/js/vite-plugin.js'; // [tl! focus]
 
-Vite HMR is perfect for apps that use SPA frameworks like Vue or React to build the UI. It even works on real devices,
-not just simulators! As long as the device is on the same network as the development machine.
+export default defineConfig({
+    plugins: [
+        laravel({
+            input: ['resources/css/app.css', 'resources/js/app.js'],
+            refresh: true,
+            hotFile: nativephpHotFile(), // [tl! focus]
+        }),
+        tailwindcss(),
+        nativephpMobile(),
+    ]
+});
+```
 
 <aside>
 
-#### Livewire and HMR on real devices
-
-Full hot reloading support for Livewire on real devices is not yet available.
-
-</aside>
+#### Two at a time, baby!
 
-### Configuration
+If you're developing on macOS, you can run both Android and iOS watchers at the same time in separate terminals:
 
-You can configure the folders that the `watch` command pays attention to in your `config/nativephp.php` file:
+```shell
+# Terminal 1
+php artisan native:watch ios
 
-```php
-'hot_reload' => [
-    'watch_paths' => [
-        'app',
-        'routes',
-        'config',
-        'database',
-        // Make sure "public" is listed in your config [tl! highlight:1]
-        'public',  
-    ],
-]
+# Terminal 2
+php artisan native:watch android
 ```
 
-### Order matters
-
-Depending on which order you run these commands, you may find that hot reloading doesn't work immediately. It's often
-best to get the commands running, get your app open, and then make a request to a new screen to allow your app to pick
-up the `hot` file's presence and connect to the HMR server.
+This way you can see your changes reflected in real-time on both platforms **at the same time**. Wild.
 
+</aside>
 
-<aside>
+This is useful during development for quickly testing changes without re-compiling your entire app. When you make
+changes to any files in your Laravel app, the web view will be reloaded and your changes should show almost immediately.
 
+Vite HMR is perfect for apps that use SPA frameworks like Vue or React to build the UI. It even works on real devices,
+not just simulators! As long as the device is on the same network as the development machine.
 
+**Don't forget to add `public/ios-hot` and `public/android-hot` to your `.gitignore` file!**
 
-#### Skip the prompts
+<aside>
 
-If you are tired of prompts, you can run most commands - like `native:run` - with arguments and options that allow you
-to skip various prompts. Use the `--help` flag on a command to find out what values you can pass directly to it:
+#### Real iOS Devices Support
 
-```shell
-php artisan native:run --help
-```
+Full hot reloading support works best on simulators. Full hot reloading support for non-JS changes on real iOS devices
+is not yet available.
 
 </aside>