Wayfinder + Precognition catch up with Laravel's QUERY routes

Laravel 13.35 gave you Route::query(). Your routes file was ready. Your TypeScript client was not. Wayfinder 0.1.22 and Precognition 2.1.1 close that gap: typed .query() helpers, form spoofing, and live validation with a body.

What’s new at a glance#

If you already ship Route::query() from Laravel 13.35, this is the front-end half of that story.

Why QUERY again (one paragraph)#

QUERY is a safe, idempotent method with a request body — think “GET with JSON filters”. Laravel registered it in 13.35; Wayfinder and Precognition now speak it without casting everything to POST.

Wayfinder: typed .query() and form spoofing#

Before 0.1.22, a route registered with Route::match(['QUERY'], …) already generated a URL, but the Method type in wayfinder.ts stopped at "options". RouteDefinition<"query"> failed to type-check. #324 adds "query" to that union.

use App\Http\Controllers\SearchController;

Route::query('/search', [SearchController::class, 'index'])
    ->name('search.index');

Route::match(['GET', 'QUERY'], '/search/{type}', [SearchController::class, 'show'])
    ->name('search.show');

After php artisan wayfinder:generate:

import { search } from '@/routes'

// QUERY-only route
search.index()        // { url: '/search', method: 'query' }
search.index.query()  // same

// GET + QUERY route: default stays GET; pick QUERY explicitly
search.show('posts')        // { url: '/search/posts', method: 'get' }
search.show.query('posts')  // { url: '/search/posts', method: 'query' }

HTML forms cannot send QUERY. Wayfinder spoofs it the same way it spoofs PUT:

search.index.form()
// { action: '/search?_method=QUERY', method: 'post' }

search.show.form.query('posts')
// { action: '/search/posts?_method=QUERY', method: 'post' }

Symfony’s Request allows overriding the method to QUERY (it only blocks GET, HEAD, CONNECT and TRACE), so Laravel’s method spoofing middleware accepts it.

Call it with fetch (Inertia does not speak QUERY yet)#

Inertia’s Method type is still get | post | put | patch | delete as of 3.9.1, so router.visit({ method: 'query' }) will not type-check. Use Wayfinder’s definition with fetch (or axios), and keep CSRF in mind for web routes:

import { search } from '@/routes'

async function runSearch(filters: Record<string, unknown>) {
  const def = search.index.query() // { url: '/search', method: 'query' }
  const res = await fetch(def.url, {
    method: 'QUERY', // uppercase for picky clients / Fetch
    headers: {
      'Content-Type': 'application/json',
      'X-XSRF-TOKEN': decodeURIComponent(
        document.cookie.match(/XSRF-TOKEN=([^;]+)/)?.[1] ?? '',
      ),
      Accept: 'application/json',
    },
    credentials: 'same-origin',
    body: JSON.stringify(filters),
  })
  return res.json()
}

When Inertia adds QUERY, you will be able to pass the Wayfinder object straight through. Until then, Precognition (next section) is the polished path for live validation against a QUERY route.

Precognition: client.query() for live validation#

Precognition 2.1.1 adds a query method next to post / put / patch. Like those, data goes in the request body, not as query-string params. GET and DELETE still merge into params.

import { useForm } from 'laravel-precognition-vue'
import { search } from '@/routes'

const form = useForm('query', search.index.url(), {
  q: '',
  category: null as string | null,
  price_min: null as number | null,
  price_max: null as number | null,
  tags: [] as string[],
})

// On each field change, Precognition hits the QUERY route with a JSON body
form.validate('q')

Under the hood that is client.query(url, data) → mergeConfig('query', …) → body merge (not params). The Precognition suite asserts config.method === 'query' and that data is present.

Optional peer fix (#176)#

Same tag also fixes the axios adapter to use the default export, so the optional axios peer can be absent when you use the fetch client. If you saw odd import errors after dropping axios, bump to 2.1.1.

Shared URI, middleware aliases, barrel import#

Three more Wayfinder fixes in 0.1.22 worth knowing:

The shared-URI fix is the one you feel when you have:

Route::post('/actions/{name}', ActionController::class)->name('actions.run');
Route::get('/actions/{name}', ActionController::class)->name('actions.show');

Before #303 the generated action file did not compile. After it, you get distinct keys (post /actions/{name} vs get /actions/{name}) and you still pick the route explicitly.

Upgrade notes#

No breaking changes in either package for existing GET/POST routes. Adopting QUERY on a route is opt-in.

# After adding Route::query('/search', ...) and updating Wayfinder:
php artisan wayfinder:generate
rg -n "method: .query.|\"query\"" resources/js/routes resources/js/actions | head

Recap#

• Laravel had Route::query() since 13.35; Wayfinder 0.1.22 and Precognition 2.1.1 make it usable from TypeScript.
• Wayfinder: search.query(), search.form.query() with _method=QUERY spoofing.
• Precognition: client.query(url, data) sends a body and keeps CSRF.
• Also in Wayfinder 0.1.22: shared-URI-by-verb keys, middleware-alias URL defaults, barrel self-import fix.

FAQ#

Next steps#

• Laravel 13.35: QUERY routes, Markdown responses and model defaults()
• Wayfinder query-string helpers in Vue
• Laravel 13.36: validation rule builders, olap() and sticky queues
• MDN: HTTP QUERY method

Sources#

• laravel/wayfinder v0.1.22 release notes
• wayfinder#324 Support the QUERY HTTP method
• wayfinder#303 Key routes that share a URI by verb
• wayfinder#295 Resolve middleware aliases when inferring URL defaults
• wayfinder#317 Fix barrel self-import
• precognition#179 Add support for the QUERY method
• precognition#176 axios default-export fix
• framework#61797 Add QUERY route method support
• RFC 9110 / QUERY drafts via MDN