Skip to content

Displays JS errors in browsers. Shows sources. Use with any framework. 💥✨

License

Notifications You must be signed in to change notification settings

xpl/panic-overlay

Repository files navigation

panic-overlay BETA 💥✨Build Status NPM

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

Screen Shot 2019-03-11 at 00 11 00

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.

<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

Screen Shot 2019-04-06 at 00 56 17

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

Screen Shot 2019-05-15 at 17 38 15