v4.0.0

Migration

cache Is Now payloadCache

The option that controls whether a response is kept in the Nuxt payload is named for what it does, so cache is free for its RequestInit meaning:

 const site = await $kql(query, {
-  cache: false,
+  payloadCache: false
 })

It is a compile error either way, so the rename surfaces on upgrade. The same rename applies to $kirby. useKql and useKirbyData lose the option altogether, see below.

useKql and useKirbyData Have No payloadCache Option

Both composables cached a response under the same key Nuxt stores its own result under, which meant a refresh was answered with the previous result – and, where a transform was set, with a result that had already been transformed once. Nuxt's async data owns the entry now: the key still comes from the request, so two call sites asking for the same thing continue to share one round trip, and refresh() sends the request again. Drop the option; $kql and $kirby keep it.

$kql and $kirby Cache Under Their Own Key

Both used to read the entry useKql and useKirbyData fill, which holds whatever their transform returned – so the same query could come back in a shape the return type does not describe. They keep their own entry now. A query shared with a composable costs one more round trip in return.

The Server Cache Is No Longer Switchable Per Call

A request used to carry its cache value to the proxy route, where it gated the Nitro cache alongside the server.cache module option. A caller could therefore bypass your server cache. The module option decides alone now, and payloadCache reaches no further than the Nuxt payload.

useKql and useKirbyData Forward Every Async Data Option

Both composables used to hand-pick which options reached useAsyncData, so deep, dedupe, getCachedData, pick and transform type-checked but did nothing. They now work as documented for Nuxt's own composables.

language Travels as a Header, Not a Path Prefix

useKirbyData and $kirby used to prepend the language code to the path, so useKirbyData('api/notes', { language: 'de' }) requested de/api/notes. Both now send the code as the X-Language header instead, which is what Kirby reads on API routes, and the path is left as written. useKql and $kql already sent the header and are unaffected.

Nothing changes for a multi-language Kirby that resolves the language from the header. Drop the workaround if you were stripping the prefix on the Kirby side.

If you fetch a page by its own path rather than through the API – with the headless.globalRoutes option of Kirby Headless – the header reaches the page from 8.1 on. On earlier versions the language belongs in the path you request:

const { data } = await useKirbyData(`${locale.value}/about`)

See Multi-Language Sites for both cases.

prefix Removed in Favor of kqlPath

The prefix module option is gone; rename the key and keep the value:

 export default defineNuxtConfig({
   kirby: {
-    prefix: 'api/query',
+    kqlPath: 'api/query',
   },
 })

It was deprecated in v3.0.1 and warned at build time. A prefix left in place is now ignored, so kqlPath falls back to api/query or api/kql depending on the authentication method – which surfaces as 404s at request time rather than as a build error.

The #nuxt-kql Import Alias Is Gone

The back-compat alias kept through v3 has been removed. Types come from kirby-types, which the module installs for you:

-import type { KirbyQueryRequest } from '#nuxt-kql'
+import type { KirbyQueryRequest } from 'kirby-types'

#nuxt-kirby is the alias for prefetched queries and re-exports the same types, so it works here as well.

---

   🚨 Breaking Changes

• Send the language as X-Language instead of a path prefix  -  by @johannschopplich (60d98)
• Remove the deprecated prefix option and #nuxt-kql alias  -  by @johannschopplich (f65b1)
• Rename the payload cache option and keep the server cache server-side  -  by @johannschopplich (89f7a)
• Let Nuxt own the payload entry of useKql and useKirbyData  -  by @johannschopplich (aacc1)

   🐞 Bug Fixes

• Import defineCachedFunction from the public nitropack entry  -  by @johannschopplich (bb3cf)
• Send the language as X-Language from the server imports too  -  by @johannschopplich (05c10)
• Run the docs scripts from the docs workspace  -  by @johannschopplich (b1cfb)
• Keep the credentials header from joining with a caller's own  -  by @johannschopplich (01fab)
• Forward every async data option instead of a hand-picked subset  -  by @johannschopplich (579bd)
• Derive the server cache key from the request, not from the caller  -  by @johannschopplich (893b9)
• Seed the payload on the server when payloadCache is off  -  by @johannschopplich (8ee69)
• Give kqlPath a default for every authentication method  -  by @johannschopplich (76800)
• Keep $kql and $kirby out of the composables cache entry  -  by @johannschopplich (fe5e8)
• kit: Annotate the logger so its type resolves without consola  -  by @johannschopplich (6cdc3)

   🏎 Performance

• Encode for the cache only when the cache is on  -  by @johannschopplich (55e2e)

    View changes on GitHub