Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Nuxe provides a first-class error system built around a single NuxeError class. Whether an error originates in a server API route, a middleware guard, or deep inside a Vue component, the same primitives — createError, showError, useError, and clearError — let you surface and dismiss it consistently across SSR and client-side navigation.

​
NuxeError

NuxeError extends the native Error class with HTTP-oriented fields that map naturally to server responses and UI display: 
class NuxeError extends Error {
  readonly statusCode: number        // HTTP status code, defaults to 500
  readonly statusMessage: string     // Short human-readable description, e.g. "Not Found"
  readonly description?: string      // Longer explanation (optional)
  readonly data?: unknown            // Arbitrary structured payload (optional)
  // Inherits: message, name ('NuxeError'), stack
}

​
createError(payload)

createError is the factory for NuxeError. It accepts three input shapes so you can create errors without always constructing the full payload object: 
import { createError } from '@dvlkit/nuxe'

throw createError({
  statusCode: 404,
  statusMessage: 'Not Found',
  description: 'The requested page does not exist.',
  data: { path: '/missing-page' },
})
Use createError in server API routes to return proper HTTP status codes. When you throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }) inside a defineEventHandler, the h3 layer serialises the error and sets the response status automatically.

​
showError(err)

Call showError inside a Vue component to both update the app’s error state (triggering app/error.vue) and throw the error so component execution stops: 
// Inside a Vue component
import { showError } from '@dvlkit/nuxe'

async function loadData() {
  const res = await fetch('/api/protected')
  if (res.status === 401) {
    showError({ statusCode: 401, statusMessage: 'Unauthorized' })
  }
}
showError accepts the same input shapes as createError — a NuxeErrorPayload object, a plain string, or a native Error.

​
useError()

useError returns a reactive Ref<NuxeError | null> that reflects the current error state. It is null when no error is active. 
import { useError } from '@dvlkit/nuxe'

const error = useError()
// error.value is a NuxeError when an error is active, or null

​
clearError(options?)

Call clearError to dismiss the current error and optionally redirect the user to a different route. Typically invoked from a button in app/error.vue. 
import { clearError } from '@dvlkit/nuxe'

// Dismiss the error and stay on the current URL
clearError()

// Dismiss and redirect to the home page
clearError({ redirect: '/' })
​
options.redirect
string
A route path to push via Vue Router after clearing the error. The navigation happens after error.value is set to null.

​
isNuxeError(err)

A TypeScript type guard that returns true when err is a NuxeError instance (or a plain object shaped like one, which can occur after SSR deserialisation): 
import { isNuxeError } from '@dvlkit/nuxe'

if (isNuxeError(err)) {
  console.log(err.statusCode, err.statusMessage)
}

​
serializeError / deserializeError

Nuxe serialises errors into the SSR payload so the client can hydrate the exact same error state. You rarely call these directly, but they are available when building custom server rendering utilities: 
import { serializeError, deserializeError } from '@dvlkit/nuxe'

// SSR side — converts NuxeError → plain object for JSON embedding
const payload = serializeError(err) // NuxeErrorPayload | null

// Client side — converts the plain object back to a NuxeError instance
const error = deserializeError(payload)

​
Custom app/error.vue

When any error is active, Nuxe unmounts the normal page tree and renders app/error.vue instead. The component receives the current NuxeError as the error prop. The playground’s app/error.vue shows a clean example — displaying the status code and message, setting the page title, and providing a “Go home” link that calls clearError: 
<!-- app/error.vue -->
<script setup lang="ts">
import { useHead } from '@dvlkit/nuxe'
import type { NuxeError } from '@dvlkit/nuxe'

const props = defineProps<{
  error: NuxeError
}>()

useHead({
  title: `${props.error.statusCode} — ${props.error.statusMessage}`,
})
</script>

<template>
  <div class="flex min-h-[50vh] flex-col items-center justify-center p-8 text-center">
    <h1 class="text-6xl font-bold text-slate-900 dark:text-slate-100">{{ error.statusCode }}</h1>
    <p class="mt-4 text-xl text-slate-600 dark:text-slate-300">{{ error.statusMessage }}</p>
    <RouterLink
      to="/"
      class="mt-8 rounded-md bg-indigo-500 px-6 py-2 text-white transition hover:bg-indigo-600"
    >
      Go home
    </RouterLink>
  </div>
</template>
1

Create app/error.vue

Add an app/error.vue file to your project. Nuxe detects it automatically — no registration required.
2

Accept the error prop

Declare defineProps<{ error: NuxeError }>() to receive the active error with full TypeScript types.
3

Display status information

Render error.statusCode and error.statusMessage so users understand what went wrong.
4

Provide a recovery path

Add a button or link that calls clearError({ redirect: '/' }) so the user can return to a working page without a hard reload.

Build docs developers (and LLMs) love

Get started for freeTalk to us