README.md

panic-overlay ^BETA 💥✨

A lightweight standalone plain JS alternative to react-error-overlay that is not tied to React / Webpack and works with any framework or even without one.

If you miss that thing from create-react-app but do not want to use that framework (e.g. you want to use Parcel as a lightweight zero-configuration alternative) — here you go!

Features

• Displays runtime errors in browsers
• Minimalistic implementation (bare DOM API), easily hackable
• Full sourcemap support (shows original code, not transpiled)
• Clickable locations (opens in VS Code), see the notes here
• Uncluttered stacktraces (collapses third party library calls)

How It Looks

Installation

npm install panic-overlay

import 'panic-overlay' // should be the very first import in your app!

Using Without A Bundler

All-in-one browser bundle (batteries included), served from a CDN of your choice. Creates a global panic object.

• jsDelivr: https://cdn.jsdelivr.net/npm/panic-overlay/build/panic-overlay.browser.js
• unpkg: https://unpkg.com/panic-overlay

<script src="https://unpkg.com/panic-overlay"></script>

Demos

Here's how you can find an example usage of panic-overlay with various bundlers:

git clone https://github.com/xpl/panic-overlay.git
cd panic-overlay
npm install

Environment	Run with	Source folder
<script> tag	npm run demo-no-bundler	demo/no-bundler
Parcel	npm run demo-parcel-vanilla	demo/parcel-vanilla
Parcel (React JSX)	npm run demo-parcel-react	demo/parcel-react
Webpack	npm run demo-webpack-vanilla	demo/webpack-vanilla
Snowpack	npm run demo-snowpack-vanilla	demo/snowpack-vanilla

Disabling Automatic Error Handling

Once imported, panic-overlay shows itself whenever an uncaught error occurs in a browser. This can be undesirable in a production environment. You can disable that behavior in run-time:

import panic from 'panic-overlay'

panic.configure ({ handleErrors: false })

Although it is better to not import the panic-overlay in a production build, to minimize the bundle size. Unfortunately, there is no universal way to do a conditional module import at compile-time — in each bundler/framework it is achieved in its own way.

Showing Manually

panic (error) // where error is either an instance of an Error or a string taken from Error.stack

VS Code Notes

Currently there is a problem with automatically determining the full file paths (at least, when using Parcel bundler), so you need to provide it manually, otherwise the error locations won't be clickable:

import panic from 'panic-overlay'

panic.configure ({ projectRoot: '/full/path/to/my/project' })

Custom Click Handler

You can intercept clicks on call stack entries. For the entry format, see this.

panic.configure ({
    stackEntryClicked (entry) {
        alert (`Clicked on ${entry.fileRelative}:${entry.line}:${entry.column}`)
    }
})

Hacking

The panic-overlay is just a GUI for the stacktracey library that provides all the magic related to callstack parsing, source code extraction and filtering of the clutter. I also maintain that library, so any contributions to its code are welcome as well.

I highly appreciate any help from the community with the following:

• Testing with various module bundlers / frameworks
• Implementing parsing of React JSX errors in stacktracey (see more here)
• Determining the full file paths for clickable locations
• Animations & better layout (probably need to center it for wide screens)

...One More Thing™

There is also a way to improve your Node errors (and the overall debug output) legibility by using the Ololog library which is built on the same stack and is maintained by me also. Check it out!

const log = require ('ololog').handleNodeErrors () // intercepts process errors

Color logging with displaying of the log call location (file + line), so you can quickly find out from the logs, where it was called in the code:

log.bright.green ('Syncing order books...')