fix(nuxt): improve global/payload error type with `NuxtError` (#25398)

docs/1.getting-started/8.error-handling.md

@@ -86,8 +86,10 @@ Customize the default error page by adding `~/error.vue` in the source directory
 
 ```vue [error.vue]
 <script setup lang="ts">
+import type { NuxtError } from '#app'
+
 const props = defineProps({
-  error: Object
+  error: Object as () => NuxtError
 })
 
 const handleError = () => clearError({ redirect: '/' })

docs/2.guide/2.directory-structure/3.error.md

@@ -9,8 +9,10 @@ During the lifespan of your application, some errors may appear unexpectedly at
 
 ```vue [error.vue]
 <script setup lang="ts">
+import type { NuxtError } from '#app'
+
 const props = defineProps({
-  error: Object
+  error: Object as () => NuxtError
 })
 </script>
 
@@ -31,12 +33,12 @@ The error page has a single prop - `error` which contains an error for you to ha
 The `error` object provides the following fields:
 ```ts
 {
-  url: string
   statusCode: number
-  statusMessage: string
-  message: string
-  description: string
-  data: any
+  fatal: boolean
+  unhandled: boolean
+  statusMessage?: string
+  data?: unknown
+  cause?: unknown
 }
 ```
 

packages/nuxt/src/app/entry.ts

@@ -10,6 +10,8 @@ import '#build/fetch.mjs'
 import { applyPlugins, createNuxtApp } from './nuxt'
 import type { CreateOptions } from './nuxt'
 
+import { createError } from './composables/error'
+
 import '#build/css'
 // @ts-expect-error virtual file
 import plugins from '#build/plugins'
@@ -29,9 +31,9 @@ if (import.meta.server) {
     try {
       await applyPlugins(nuxt, plugins)
       await nuxt.hooks.callHook('app:created', vueApp)
-    } catch (err) {
-      await nuxt.hooks.callHook('app:error', err)
-      nuxt.payload.error = (nuxt.payload.error || err) as any
+    } catch (error) {
+      await nuxt.hooks.callHook('app:error', error)
+      nuxt.payload.error = nuxt.payload.error || createError(error as any)
     }
     if (ssrContext?._renderResponse) { throw new Error('skipping render') }
 
@@ -59,9 +61,9 @@ if (import.meta.client) {
 
     const nuxt = createNuxtApp({ vueApp })
 
-    async function handleVueError(err: any) {
-      await nuxt.callHook('app:error', err)
-      nuxt.payload.error = (nuxt.payload.error || err) as any
+    async function handleVueError(error: any) {
+      await nuxt.callHook('app:error', error)
+      nuxt.payload.error = nuxt.payload.error || createError(error as any)
     }
 
     vueApp.config.errorHandler = handleVueError

packages/nuxt/src/app/nuxt.ts

@@ -84,14 +84,7 @@ export interface NuxtPayload {
   state: Record<string, any>
   once: Set<string>
   config?: Pick<RuntimeConfig, 'public' | 'app'>
-  error?: Error | {
-    url: string
-    statusCode: number
-    statusMessage: string
-    message: string
-    description: string
-    data?: any
-  } | null
+  error?: NuxtError | null
   _errors: Record<string, NuxtError | null>
   [key: string]: unknown
 }

packages/nuxt/src/core/runtime/nitro/error.ts

@@ -5,6 +5,7 @@ import { getRequestHeaders, send, setResponseHeader, setResponseStatus } from 'h
 import { useRuntimeConfig } from '#internal/nitro'
 import { useNitroApp } from '#internal/nitro/app'
 import { isJsonRequest, normalizeError } from '#internal/nitro/utils'
+import type { NuxtPayload } from '#app'
 
 export default <NitroErrorHandler> async function errorhandler (error: H3Error, event) {
   // Parse and normalize error
@@ -21,7 +22,7 @@ export default <NitroErrorHandler> async function errorhandler (error: H3Error,
       : '',
     // TODO: check and validate error.data for serialisation into query
     data: error.data as any
-  }
+  } satisfies Partial<NuxtPayload['error']> & { url: string }
 
   // Console output
   if (error.unhandled || error.fatal) {

packages/nuxt/src/core/runtime/nitro/renderer.ts

@@ -235,7 +235,7 @@ export default defineRenderHandler(async (event): Promise<Partial<RenderResponse
 
   // Whether we're rendering an error page
   const ssrError = event.path.startsWith('/__nuxt_error')
-    ? getQuery(event) as unknown as Exclude<NuxtPayload['error'], Error>
+    ? getQuery(event) as unknown as NuxtPayload['error'] & { url: string }
     : null
 
   if (ssrError && ssrError.statusCode) {