Add an option for strict route checking

[Esensats]

Description

When you type a route that doesn't exist it doesn't show any errors nor warnings in any environment IDE. Not even in runtime when the route is accessed.
I use php artisan ziggy:generate --types-only each time the routes are updated in the backend (automatically, using a watcher).
My environment: Laravel 11, PHP 8.3, Breeze Inertia Vue template, added Typescript, declared ziggy's global route

Example:

A vue page component:

<Link :href="route('invalid.route')"> <!-- No error by Typescript, nor in browser, nor in runtime (console), even though the route auto-complete works  -->
Dashboard
</Link>

When the page with this invalid link is requested (not even the route itself), the user only sees a blank white page with zero errors, not even in the Browser console nor in the Networking tab. The PHP logs emit no errors as well. I think it's critical to at least inform consumers about this potential debugging nightmare.

Suggestion

I suggest providing an option that makes Typescript yell at you when the string in the route function isn't declared by the ziggy.d.ts file. It can be named strictRoutes of type boolean for example.

Alternatives

Enforce a mechanism that makes the server throw an error to the user and logging it. Or update the Breeze Inertia template to have this error handling built-in. Or at least write in the README how to set error handling up manually

[bakerkretzmar]

Calling route('invalid.route') should definitely error and you should see it in the browser console. Is that exactly the code in your app? What page is it on in the Inertia template? Do you have anything like Sentry set up that might be swallowing errors? Are you having this issue in development mode or with a full Vite build, or both?

Making route() stricter about the route names passed into it is something I'm totally open to.

[Esensats]

Calling route('invalid.route') should definitely error and you should see it in the browser console. Is that exactly the code in your app? What page is it on in the Inertia template? Do you have anything like Sentry set up that might be swallowing errors? Are you having this issue in development mode or with a full Vite build, or both?

Making route() stricter about the route names passed into it is something I'm totally open to.

Oof, I was either extremely inattentive or it for some reason didn't show up in the browser console at the time I checked. It does indeed show up in the browser console now that I check again. Sorry for misinforming on that part.

Question, is it possible to have it check all the route calls at build-time? If not, then either way, I guess the simplest solution would be to provide an option to show the error in development time: optional Typescript error/warning.

If this solution is chosen, then the next natural question would be - where to put the option? In what configuration file? If I am not mistaken, the ziggy.js file is not made for that. I guess it'd be put as into some kind of an options param while calling app.use(ZiggyVue({strictRoutes: true})), making ZiggyVue callable, right?

[bakerkretzmar]

No clue if it's possible to check them all at build time but I kinda doubt it.

I would think it might have to be part of the ziggy:generate command so it's in the ziggy.d.ts file but I'm not sure. It may also make sense not to make it optional, but just to change Ziggy's behaviour to only allow known route names in the helper.

[Esensats]

Here, I made a wrapper:

/**
 * A wrapper for Ziggy's route helper with error handling and strict route names.
 */
// Called with no arguments - returns a Router instance
export function appRoute(): Router;
// Called with a route name and optional additional arguments - returns a URL string
export function appRoute<T extends KnownRouteName>(
    name: T,
    params?: RouteParams<T> | undefined,
    absolute?: boolean,
    errCallback?: (e: unknown) => string,
    config?: Config
): string;
export function appRoute<T extends KnownRouteName>(
    name: T,
    params?: ParameterValue | undefined,
    absolute?: boolean,
    errCallback?: (e: unknown) => string,
    config?: Config
): string;
// Called with configuration arguments only - returns a configured Router instance
export function appRoute(
    name: undefined,
    params: undefined,
    absolute?: boolean,
    errCallback?: (e: unknown) => string,
    config?: Config
): Router;

export function appRoute(
    name?: KnownRouteName | undefined,
    params?: RouteParams<KnownRouteName> | ParameterValue | undefined,
    absolute?: boolean,
    errCallback: (e: unknown) => string = (e) => {
        console.error(e);
        return "#";
    },
    config?: Config
): string | Router {
    try {
        if (
            name === undefined &&
            params === undefined &&
            absolute === undefined &&
            config === undefined
        ) {
            return route() as unknown as Router;
        }
        if (name === undefined) {
            return route(
                name,
                params as undefined,
                absolute,
                config
            ) as unknown as Router;
        }
        return route(
            name,
            params as ParameterValue,
            absolute,
            config
        ) as unknown as string;
    } catch (e) {
        // Possibly redirect to error page or show a toast
        return `${errCallback(e)}` || "#";
    }
}

Used like this:

<Link :href="appRoute('dashboard')"> <!-- if invalid then typescript error, autocomplete still works -->
Dashboard
</Link>

If the route doesn't exist, typescript shows an error. Basically it just uses KnownRouteName instead of RouteName. This example in particular also "handles" the error (by that I mean the page does not turn completely blank on error).

[Esensats]

Also don't forget about this:

    appRoute().current('dashboard')
// -------------------- ^ string is not strict, because it keeps using `RouteName`, but autocomplete still works

Only direct calls like appRoute('dashboard') are strict with this approach

[Andyuu]

Hi @bakerkretzmar I looked into this and found a simple solution to allow people to enable strict mode if they want it

Library index.d.ts

/**
 * A list of routes and their parameters and bindings.
 *
 * Extended and filled by the route list generated with `php artisan ziggy:generate --types`.
 */
export interface RouteList {}

export interface TypeConfig {}

/**
 * A route name registered with Ziggy.
 */
type KnownRouteName = keyof RouteList;

/**
 * A route name, or any string.
 */
type RouteName =  TypeConfig['strict'] extends true
    ? KnownRouteName
    : KnownRouteName | (string & {});

The same way as the RouteList, the TypeConfig interface can be overridden

User code ziggy-strict.d.ts

declare module 'ziggy-js' {
    export interface TypeConfig {
        strict: true;
    }
}

When the override is not present, it currently ends up being any. So with a slight adjustment, it works when no strict key is set

type RouteName =  'strict' extends keyof TypeConfig
  ? TypeConfig['strict'] extends true
    ? KnownRouteName
    : KnownRouteName | (string & {})
  : KnownRouteName | (string & {});  

[bakerkretzmar]

This is 🔥 thanks!