Making Browserify bundle play nice with ReactDevTools

Question

React 0.13.3

I started using Browserify to organize my frontend React code. I'm also using the React Developer Tools Chrome extension for debugging. However, I'm having trouble with some very simple React code.

var React = require('react/addons');

//React DEV-TOOLS requires React to be on the global scope. Scope is hidden when bundling
window.React = React;

var App = React.createClass({
    render: function(){
        return (
            <div>
               <p>Hello world</p> <!-- Renders fine -->
            </div>
        )
    }
});

React.render(
    <App />,
    document.getElementById('content')
);

The following code actually works, and "Hello world" renders fine. The trouble starts when I start the React debugger in my console. I would expect it to say the following:

<Top Level>
    <App>...</App>
</Top Level>

But instead, it simply says:

<Top Level></Top Level>

How can <App> be rendered without the React devtools recognizing them?

Answer 1

It seems enough people have stumbled upon this matter, and the official guide does not mention this particular symptom. After gathering enough evidence, it is best that an answer is posted here, even if there might be other causes to this <Top Level></Top Level> issue.

The React DevTools may not work if there is more than one instance of React in the bundle. This is often related with an incorrect bundling tool configuration (browserify or webpack) in a particular component. React components (and other libraries supported by React, such as Mixins) should always have react as a peerDependency in npm and as an "external" in browserify/webpack. This will make it so that a distributable version of the module will not embed React for itself. In addition, if React add-ons are used, "react/addons" may also have to be registered as an external dependency.

In cases where this was not followed, the mere inclusion of the module with require (or ES6's import) will render the dev tools useless. When another instance of React emerges, that one will register itself as the source of the element tree, which is why an empty element is shown. I have tracked down this bug in react-loaders (issue #2), and it's now fixed since 1.2.3. The same might have happened to react-google-maps according to what @Carpetfizz said, although I have not looked deeply into this case.

One easy trick to debug this is to take a barebones module + web page and iteratively add require instructions until the React dev tools stop working. Once the faulty component is found, file an issue.

var React = require('react');
var Loader = require('react-loaders'); // testing react-loaders

var App = React.createClass({
    render: function(){
        return (
            <div>
               <p>Check the React tab!</p>
            </div>
        )
    }
});

React.render(<App />, document.getElementById('container'));

Another peculiar solution was carried out in the React packages for Meteor, where the development runtime was changed to load the main instance of React last (commit).

This topic was lifted in issue #90, which helped identify more cases of non-compliant packages.