feat(nuxt): improve error dx for users

docs/content/2.guide/2.features/7.error-handling.md

@@ -82,10 +82,22 @@ This function will return the global Nuxt error that is being handled.
 
 ### `throwError`
 
-* `function throwError (err: string | Error): Error`
+* `function throwError (err: string | Error | { statusCode, statusMessage }>): Error`
 
 You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or `setup()` functions. It will trigger a full-screen error page (as above) which you can clear with `clearError`.
 
+### Example
+
+```vue [pages/movies/[slug].vue]
+<script setup>
+const route = useRoute()
+const { data, error } = await useFetch(`/api/movies/${route.params.slug}`)
+if (error.value) {
+  return throwError({ statusCode: 404, statusMessage: 'Page Not Found' })
+}
+</script>
+```
+
 ::ReadMore{link="/api/utils/throw-error"}
 ::
 

docs/content/3.api/3.utils/throw-error.md

@@ -6,10 +6,11 @@ Within your pages, components and plugins you can use `throwError` to throw an e
 
 **Parameters:**
 
-- `error`: `string | Error`
+- `error`: `string | Error | Partial<H3Error>`
 
 ```js
 throwError("😱 Oh no, an error has been thrown.")
+throwError({ statusCode: 404, statusMessage: "Page Not Found" })
 ```
 
 The thrown error is set in the state using [`useError()`](/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
@@ -18,3 +19,20 @@ The thrown error is set in the state using [`useError()`](/api/composables/use-e
 
 ::ReadMore{link="/guide/features/error-handling"}
 ::
+
+## Throwing errors in API routes
+
+You can use `createError` from [`h3`](https://github.com/unjs/h3) package to trigger error handling in server API routes.
+
+**Example:**
+
+```js
+import { createError } from 'h3'
+
+export default eventHandler(() => {
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Page Not Found'
+  })
+}
+```

packages/nuxt/src/app/components/nuxt-error-page.vue

@@ -34,7 +34,7 @@ const stacktrace = (error.stack || '')
 const statusCode = String(error.statusCode || 500)
 const is404 = statusCode === '404'
 
-const statusMessage = error.statusMessage ?? is404 ? 'Page Not Found' : 'Internal Server Error'
+const statusMessage = error.statusMessage ?? (is404 ? 'Page Not Found' : 'Internal Server Error')
 const description = error.message || error.toString()
 const stack = process.dev && !is404 ? error.description || `<pre>${stacktrace}</pre>` : undefined
 

packages/nuxt/src/app/composables/error.ts

@@ -1,14 +1,19 @@
+import { createError, H3Error } from 'h3'
 import { useNuxtApp, useState } from '#app'
 
 export const useError = () => {
   const nuxtApp = useNuxtApp()
   return useState('error', () => process.server ? nuxtApp.ssrContext.error : nuxtApp.payload.error)
 }
 
-export const throwError = (_err: string | Error) => {
+export const throwError = (_err: string | Error | Partial<H3Error>) => {
   const nuxtApp = useNuxtApp()
   const error = useError()
-  const err = typeof _err === 'string' ? new Error(_err) : _err
+  const err = typeof _err === 'string'
+    ? new Error(_err)
+    : _err && typeof _err === 'object' && !(_err instanceof Error)
+      ? createError(_err)
+      : _err
   nuxtApp.callHook('app:error', err)
   if (process.server) {
     nuxtApp.ssrContext.error = nuxtApp.ssrContext.error || err

packages/nuxt/src/app/plugins/router.ts

@@ -106,11 +106,6 @@ export default defineNuxtPlugin<{ route: Route, router: Router }>((nuxtApp) => {
       // Resolve route
       const to = getRouteFromPath(url)
 
-      if (process.client && !nuxtApp.isHydrating) {
-      // Clear any existing errors
-        await callWithNuxt(nuxtApp, clearError)
-      }
-
       // Run beforeEach hooks
       for (const middleware of hooks['navigate:before']) {
         const result = await middleware(to, route)
@@ -127,6 +122,10 @@ export default defineNuxtPlugin<{ route: Route, router: Router }>((nuxtApp) => {
       Object.assign(route, to)
       if (process.client) {
         window.history[replace ? 'replaceState' : 'pushState']({}, '', url)
+        if (!nuxtApp.isHydrating) {
+          // Clear any existing errors
+          await callWithNuxt(nuxtApp, clearError)
+        }
       }
       // Run afterEach hooks
       for (const middleware of hooks['navigate:after']) {

packages/nuxt/src/pages/runtime/router.ts

@@ -125,11 +125,6 @@ export default defineNuxtPlugin((nuxtApp) => {
       }
     }
 
-    if (process.client && !nuxtApp.isHydrating) {
-      // Clear any existing errors
-      await callWithNuxt(nuxtApp, clearError)
-    }
-
     for (const entry of middlewareEntries) {
       const middleware = typeof entry === 'string' ? nuxtApp._middleware.named[entry] || await namedMiddleware[entry]?.().then(r => r.default || r) : entry
 
@@ -152,6 +147,10 @@ export default defineNuxtPlugin((nuxtApp) => {
 
   router.afterEach(() => {
     delete nuxtApp._processingMiddleware
+    if (process.client && !nuxtApp.isHydrating) {
+      // Clear any existing errors
+      callWithNuxt(nuxtApp, clearError)
+    }
   })
 
   nuxtApp.hook('app:created', async () => {