Skip to content
Vue Equipment

MagicError

MagicError is a composable and a class used throughout Vue Equipment for error handling and logging. It allows you to throw custom errors including a source, error code, timestamp and an automatically prefixed message.

View source View as Markdown

Anatomy

<script setup>
import { useMagicError, type UseMagicErrorReturn } from '@maas/vue-equipment/plugins/MagicError'

const { logError, logWarning, throwError } = useMagicError({
  prefix: 'CustomPrefix',
  source: 'CustomSource',
})

logError('An error occurred')
logWarning('This is a warning')

throwError({ message: 'An error occurred', errorCode: 'custom_error_code' })
</script>

Installation

CLI

Add @maas/vue-equipment to your dependencies.

pnpm add @maas/vue-equipment

Nuxt

The plugin is available as a Nuxt module. In your Nuxt config file add @maas/vue-equipment/nuxt to your modules and add MagicError to the plugins in your configuration.

export default defineNuxtConfig({
  modules: ['@maas/vue-equipment/nuxt'],
  vueEquipment: {
    plugins: ['MagicError'],
  },
})

Composable

In order to throw errors from anywhere within your app, import the useMagicError composable.

import { useMagicError, type UseMagicErrorReturn } from '@maas/vue-equipment/plugins/MagicError'

const { throwError, logError, logWarning } = useMagicError({
  prefix: 'CustomPrefix',
  source: 'CustomSource',
})

Peer Dependencies

MagicError has no optional peer dependencies. It only relies on the core peer dependencies, which npm, pnpm and bun install automatically.

Typescript

The useMagicError composable is fully typesafe. The UseMagicErrorReturn type can be imported seperately.

Assert

Due to how the typescript compiler works, you need to explicitly type the return value when calling useMagicError and refrain from destructuring it.

import { inject } from 'vue'
import {
  useMagicError,
  type UseMagicErrorReturn,
} from '@maas/vue-equipment/plugins/MagicError'

const magicError: UseMagicErrorReturn = useMagicError()
const customRef = inject('custom-ref', undefined)

magicError.assert(customRef, {
  message: 'customRef must be provided',
  errorCode: 'custom_ref_required',
})

alert('customRef is valid')