@kong-ui-public/error-boundary v2.1.18

@kong-ui-public/error-boundary

A Vue error boundary component to capture unhandled errors that allows for providing a fallback UI and error callback function via Vue's onErrorCaptured hook.

• Features
• Requirements
• Usage
  • Install
  • Register
  • Slots
  • Props

Features

• Renderless (by default) Vue component that captures uncaught errors from child components and prevents the error from propagating further
• Allows passing in a list of tags to forward along to the onError callback function.
• Allows providing an error callback function (defined inline or during global Vue plugin initialization)
• Provides a fallback slot to allow a host app to provide an error UI that also provides access to the error and context (tags, etc.)
• Allows for nested ErrorBoundary components in the DOM. Any nested ErrorBoundary components will inherit the tags of any parent ErrorBoundary component
• See the package sandbox for more examples

The ErrorBoundary component will always capture any unhandled errors and prevent them from further propagating. This is essentially saying "this error has been handled and should be ignored." It will prevent any additional ErrorBoundary components from receiving the error and prevent additional errorCaptured hooks or app.config.errorHandler from being invoked for this error.

The ErrorBoundary component can be used to wrap a single component or an entire tree of children, tagging any errors that are captured in the DOM tree. The closest ErrorBoundary to the buggy component will capture the error; therefore the closest ErrorBoundary must also provide the fallback UI, if desired.

When nesting ErrorBoundary components, the tags from any parent ErrorBoundary component will be passed down to its child ErrorBoundary components and included in their ErrorBoundaryCallbackParams.

<template>
  <div class="my-page">
    <!-- 1 -->
    <ErrorBoundary :tags="['team-settings']">
      <SettingsComponent />
      <form>
        <!-- 2 -->
        <ErrorBoundary :tags="['team-billing']">
          <BuggyComponent />
          <!-- 3 -->
          <ErrorBoundary :tags="['team-core-ui']">
            <CreditCardComponent />
            <!-- The fallback slot has access to all params -->
            <template #fallback="{ error, context }">
              <div class="fallback-content">
                <p>This component has custom fallback UI; most likely just an icon, etc.</p>
                <p class="error-message">{{ context.componentName }}: {{ error.message }}</p>
              </div>
            </template>
          </ErrorBoundary>
        <ActionButtonsComponent />
        </ErrorBoundary>
      </form>
    </ErrorBoundary>
  </div>
</template>

Looking at the numbered examples above:

1. team-settings will be tagged if any child of this component throws an uncaught error, including the <SettingsComponent> all the way down to the <CreditCardComponent>
2. team-settings and team-billing will be tagged for anything inside the <form> element
3. team-core-ui will only be tagged if the <CreditCardComponent> throws an error, as it is the only DOM child of its error boundary.

Requirements

• vue must be initialized in the host application

Usage

Note: if your application utilizes the private KonnectAppShell component, this ErrorBoundary component is already registered globally within the app along with the preferred onError callback function.

Install

Install the package in your host application

yarn add @kong-ui-public/error-boundary

Register

You can register the ErrorBoundary component in your app globally or locally in another component.

Note: There are no style imports for this package.

Global Registration

When registering the component globally via the default export Vue plugin, you may provide a default onError callback to be used throughout your application for all instances of the ErrorBoundary component.

You may still override this global callback on individual instances of the component by passing a function to the onError component prop. (This includes providing an empty function to disable the global behavior)

// Global registration
import { createApp } from 'vue'
import ErrorBoundary from '@kong-ui-public/error-boundary' // No style imports needed
// Datadog package example
import { datadogRum } from '@datadog/browser-rum'

const app = createApp(App)

app.use(ErrorBoundary, {
  // Provide a global, default `onError` callback for all ErrorBoundary instances
  onError({ error, context }) {
    // Example of sending errors to Datadog
    datadogRum.addError(error, {
      ui: context,
    })
  },
})

In-Component Registration

When registering the component locally, you can provide the onError callback as a prop.

<!-- Local registration -->
<template>
  <ErrorBoundary
    :on-error="customErrorCallback"
    :tags="myTags"
  >
    <BuggyComponent />
  </ErrorBoundary>
</template>

<script setup lang="ts">
import { ErrorBoundary } from '@kong-ui-public/error-boundary' // No style imports needed

const myTags = ['first-tag', 'another-tag']
const customErrorCallback = ({ error, context }) => {
  // Do something fancy
}
</script>

Slots

default

The default slot should be utilized for your "potentially buggy" Vue component(s). The default slot can handle a single child, or an entire tree of child components/elements.

fallback

The fallback slot can optionally be used to provide a fallback UI should any child component (not already wrapped with another ErrorBoundary component) thrown an unhandled error. The default fallback behavior is to render nothing in the UI.

The fallback slot has access to all of the ErrorBoundaryCallbackParams as slot props:

<ErrorBoundary :tags="myTags">
  <BuggyComponent />
  <template #fallback="{ error, context }">
    <!-- Your fallback UI here -->
  </template>
</ErrorBoundary>

The closest ErrorBoundary to the buggy component will capture the error; therefore, the closest ErrorBoundary must also provide the fallback UI, if desired.

Props

tags

• type: String[]
• required: false
• default: []

A list of strings to "tag" the captured error with that are passed along to the onError callback.

You may then utilize these tags to send context along with any function called in the onError callback.

For example, if you want to provide custom attributes to error logs on Datadog, you can pass in an array of strings to add to the logged error's custom attributes.

onError

• type: Function as PropType<(params: ErrorBoundaryCallbackParams) => void>
• required: false
• default: []

A function to be called from the ErrorBoundary component when an error in a child component is captured. Receives params of ErrorBoundaryCallbackParams.

Note: Providing a callback function via the onError prop will take precedence over any callback function defined during global registration. You can also provide an empty function in order to prevent the global callback from being executed.