Skip to main content

Error handling

You can use standard web techniques to handle errors in checkout UI extensions but you may need to account for how they run inside of a Web Worker.

Anchor to handling-any-errorHandling any error

Add an unhandledrejection listener for promise rejections or an error listener for other exceptions like Javascript runtime errors or failures to load a resource.

Handling any error

// For unhandled promise rejections
self.addEventListener(
'unhandledrejection',
(error) => {
console.warn(
'event unhandledrejection',
error,
);
},
);

// For other exceptions
self.addEventListener('error', (error) => {
console.warn('event error', error);
});

Anchor to third-party-librariesThird party libraries

You can use error reporting libraries like Bugsnag or Sentry. However, they might require extra configuration because UI extensions run inside of a Web Worker. You should also consider using source maps to help debug errors.

Tip

You must request network access to transmit errors to a third party service.

Anchor to sentrySentry (recommended)

Initialize Sentry following their Web Worker guide. We recommend disabling the default integrations to be sure it will run within a Web Worker. You'll need to add event listeners manually.

If you are writing your UI extension in React, you can follow Sentry's React integration guide to get additional context on errors thrown while rendering your components. Integrations like tracing do not currently run in Web Workers (issue).

Sentry

import {
reactExtension,
Banner,
} from '@shopify/ui-extensions-react/checkout';
import * as Sentry from '@sentry/browser';

Sentry.init({
dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
defaultIntegrations: false,
});

self.addEventListener(
'unhandledrejection',
(error) => {
Sentry.captureException(
new Error(error.reason.stack),
);
},
);

self.addEventListener('error', (error) => {
Sentry.captureException(
new Error(error.reason.stack),
);
});

// Your normal extension code.
export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return <Banner>Your extension</Banner>;
}

Anchor to bugsnagBugsnag

Follow Bugsnag's documentation to install it for your extension. Bugsnag adds event listeners by default so there's no need to add them manually.

If you use the CDN version, you'll need to add polyfill code (see example) before importing Bugsnag because it tries to access some variables that are not available in Web Workers (details).

If you are writing your UI extension in React, you can follow Bugsnag's React integration guide to get additional context on errors thrown while rendering your components.

Bugsnag

/**
* The CDN version of Bugsnag requires this polyfill.
*/
(() => {
const document = {
documentElement: {
outerHTML: '',
createElement: () => ({}),
clientWidth: 0,
clientHeight: 0,
},
addEventListener: () => {},
};
const history = {};
const window = self;
self.window = window;
window.document = document;
window.history = history;
})();