Deep linking in NativePHP + Laravel + Inertia (React) always opens home and not target route

[MurtazaD1410]

What were you trying to do?

Description

When using NativePHP (Electron) with Laravel 12 and Inertia React, the built-in deep link handler (setDeepLinkHandler) doesn’t correctly route to the intended URL within the app.

If the app is closed, the deep link successfully opens the app, but always loads the default dashboard instead of the target route.

If the app is already open, the app window focuses (as expected), but no navigation occurs — it stays on the current page.

What happened?

Expected Behavior

The deep link (e.g. deeplinkprotocol://settings/worktime) should cause:

Laravel/Inertia to load the corresponding route (/settings/worktime) when the app starts.

Or, if the app is already running, it should trigger a frontend navigation to that route.

Actual Behavior

The application always opens the default dashboard/home.

When already open, the deep link only focuses the window — it doesn’t trigger route navigation.

How to reproduce the bug

Steps To Reproduce

Create a NativePHP + Laravel 12 project using Inertia (React).

Keep the default deep link handler:
`private setDeepLinkHandler(config) {
const deepLinkProtocol = config?.deeplink_scheme;

if (deepLinkProtocol) {
    if (process.defaultApp) {
        if (process.argv.length >= 2) {
            app.setAsDefaultProtocolClient(deepLinkProtocol, process.execPath, [resolve(process.argv[1])]);
        }
    } else {
        app.setAsDefaultProtocolClient(deepLinkProtocol);
    }

    if (process.platform !== 'darwin') {
        const gotTheLock = app.requestSingleInstanceLock();
        if (!gotTheLock) {
            app.quit();
            return;
        } else {
            app.on('second-instance', (event, commandLine) => {
                if (this.mainWindow) {
                    if (this.mainWindow.isMinimized()) this.mainWindow.restore();
                    this.mainWindow.focus();
                }

                notifyLaravel('events', {
                    event: '\\Native\\Desktop\\Events\\App\\OpenedFromURL',
                    payload: {
                        url: commandLine[commandLine.length - 1],
                    },
                });
            });
        }
    }
}

}`

Create a test HTML file with:

<a href="#" onclick="event.preventDefault(); window.location.href='deeplinkprotocol://settings/worktime';"> Open MyApp </a>

With the app closed, click the link — app opens, but only shows home.

With the app open, click the link — app focuses, but does not navigate.

Debug Output

It seems the OpenedFromURL event is not triggering a frontend (Inertia) route change.

Which operating systems have you seen this occur on?

windows

Notes

Laravel : 12.x
Inertia : 2.0 (React)
NativePHP : 2.0
OS : Windows

[gwleuverink]

Hi @MurtazaD1410 Thanks for reporting.

Deep links work but perhaps a bit differently than you might assume. It's a undocumented feature right now. Making a mental note to document this 😅

You need to listen to a OpenedFromURL event in your Laravel app. This event has a $url property you need to parse and decide what to do with. In your case pointing the main window to that url.

This might seem strange but is intentional. Devs might want to do something else entirely than routing to a specific page when a deep link has been visited.

Hope that clarifies things!