Vue Equipment
Sponsored by

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.

Overview ​

Anatomy ​

vue
<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.

sh
pnpm install @maas/vue-equipment
sh
npm install @maas/vue-equipment
sh
yarn add @maas/vue-equipment
sh
bun install @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.

js
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.

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

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

TIP

If you have installed the plugin as a Nuxt module, the composable will be auto-imported and is automatically available in your Nuxt app.

Peer Dependencies ​

If you haven’t installed the required peer dependencies automatically, you’ll need to install the following packages manually.

Package
@nuxt/kit

Installation ​

sh
pnpm install @nuxt/kit
sh
npm install @nuxt/kit
sh
yarn add @nuxt/kit
sh
bun install @nuxt/kit

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.

ts
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')