1 | # redbox-react
|
2 |
|
3 | [![Build Status](https://travis-ci.org/commissure/redbox-react.svg?branch=master)](https://travis-ci.org/commissure/redbox-react)
|
4 | [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
|
5 |
|
6 | The red box (aka red screen of death) renders an error in this “pretty” format:
|
7 |
|
8 | <img src="http://i.imgur.com/9Jhlibk.png" alt="red screen of death" width="700" />
|
9 |
|
10 | ## Usage
|
11 |
|
12 | Catch an error and give it to `redbox-react`. Works great with
|
13 |
|
14 | - [react-transform-catch-errors]
|
15 | - [Example][react-transform-example]
|
16 | - [react-transform-boilerplate]
|
17 | - [react-hot-loader]
|
18 | - :warning: ️ based on `3.0.0-beta.2`! This depends on `ErrorBoundaries` which
|
19 | will likely not land in react! You should probably not use this
|
20 | before 3.0.0 comes out.
|
21 | - [Example][react-hot-loader-example]
|
22 |
|
23 | [react-transform-catch-errors]: https://github.com/gaearon/react-transform-catch-errors
|
24 | [react-transform-example]: https://github.com/commissure/redbox-react/tree/master/examples/react-transform-catch-errors
|
25 | [react-transform-boilerplate]: https://github.com/gaearon/react-transform-boilerplate/
|
26 | [react-hot-loader]: https://github.com/gaearon/react-hot-loader
|
27 | [react-hot-loader-example]: https://github.com/commissure/redbox-react/tree/master/examples/react-hot-loader
|
28 |
|
29 | or manually:
|
30 |
|
31 | ```javascript
|
32 | import RedBox from 'redbox-react'
|
33 |
|
34 | const e = new Error('boom')
|
35 | const box = <RedBox error={e} />
|
36 | ```
|
37 |
|
38 | Here is a more useful, full-fleged example:
|
39 |
|
40 | ```javascript
|
41 | /* global __DEV__ */
|
42 | import React from 'react'
|
43 | import { render } from 'react-dom'
|
44 | import App from './components/App'
|
45 |
|
46 | const root = document.getElementById('root')
|
47 |
|
48 | if (__DEV__) {
|
49 | const RedBox = require('redbox-react').default
|
50 | try {
|
51 | render(<App />, root)
|
52 | } catch (e) {
|
53 | render(<RedBox error={e} />, root)
|
54 | }
|
55 | } else {
|
56 | render(<App />, root)
|
57 | }
|
58 | ```
|
59 |
|
60 | ## What Is This Good For?
|
61 |
|
62 | An error that's only in the console is only half the fun. Now you can
|
63 | use all the wasted space where your app would be if it didn’t crash to
|
64 | display the error that made it crash.
|
65 |
|
66 | **Please use this in development only.**
|
67 |
|
68 | ## Will this catch errors for me?
|
69 | No. This is only a UI component for rendering errors and their stack
|
70 | traces. It is intended to be used with with other existing solutions
|
71 | that automate the error catching for you. See the list at the top of
|
72 | this document or take a look at the [examples].
|
73 |
|
74 | [examples]: https://github.com/commissure/redbox-react/tree/master/examples
|
75 |
|
76 | ## Optional Props
|
77 |
|
78 | The `RedBox` component takes a couple of props that you can use to
|
79 | customize its behaviour:
|
80 |
|
81 | ### `editorScheme` `[?string]`
|
82 | If a filename in the stack trace is local, the component can create the
|
83 | link to open your editor using this scheme eg: `subl` to create
|
84 | `subl://open?url=file:///filename`.
|
85 |
|
86 | ### `useLines` `[boolean=true]`
|
87 | Line numbers in the stack trace may be unreliable depending on the
|
88 | type of sourcemaps. You can choose to not display them with this flag.
|
89 |
|
90 | ### `useColumns` `[boolean=true]`
|
91 | Column numbers in the stack trace may be unreliable depending on the
|
92 | type of sourcemaps. You can choose to not display them with this flag.
|
93 |
|
94 | ### `style` `[?object]`
|
95 | Allows you to override the styles used when rendering the various parts of the
|
96 | component. It will be shallow-merged with the [default styles](./src/style.js).
|
97 |
|
98 | If you’re using [react-transform-catch-errors] you can add these
|
99 | options to your `.babelrc` through the [`imports` property][imports].
|
100 |
|
101 | [imports]: https://github.com/gaearon/react-transform-catch-errors#installation
|
102 |
|
103 | ## Sourcemaps With Webpack
|
104 |
|
105 | If you’re using [Webpack](https://webpack.github.io) you can get
|
106 | accurate filenames in the stacktrace by setting the
|
107 | `output.devtoolModuleFilenameTemplate` settings to `/[absolute-resource-path]`.
|
108 |
|
109 | It's recommended to set the `devtool` setting to `'eval'`.
|