Debugging What React DevTools Can’t See

Hello everyone, hope you're doing really great. So I thought I would tell you a small story before I actually get started. I'm telling the story not because this is a unique one and I suspect every one of you will have a version of it. But because this is the reason why this talk exists today.

So a while ago I was working on an e-commerce application. The issue was the orders were getting stuck. It was not failing. It was not throwing any errors. Not just doing anything dramatic and all. It was just sitting there in the processing state. It was kept on processing, processing for like forever. It was just vibing there doing nothing and any developer, any engineer who will be in that situation I did the most natural thing.

I opened my React DevTools. I looked at the componentry. It was fine. I looked at the props. It was great. The hooks, everything was perfect. Everything looked fine. And then this is how my React DevTools was reacting. Then I did the, you know, second most natural thing any developer would do. I started putting console logs for every 10 lines. Hey, are you here? Hey bug are you here? And then eventually like I got succeeded with it anyway. I'm not proud of it, but that's what actually happened.

So after I got the issue resolved, I finally found the bug, which was sitting in a custom state machine that was completely outside of anything, my React DevTools or any debugging tools that I can see. So everything was perfect. But still, I can't debug that efficiently. Once that thing was done, that was wrapped up. I kept thinking about that. Why did it took so long for me? It was a very small issue, you know, if there was a way to monitor the business logic, if there was a way, then this would be the very straightforward bug that I can resolve.

No tool showed us what the state machine was doing. No tool showed me what the transition failed. We were debugging blindly in a part of the system that mattered the most. And that's what we are going to be seeing today.

So I'll tell you how I built my own custom DevTools panels to debug this, your own business logic specific things, how you can build your own. And that's what we're going to be talking about today.

So my name is Vishnu. I'm a product engineer at GetStack. So I work with the front end team that builds VoiceTag. So VoiceTag is an AI-powered phone system. Yeah, when I'm not coding, like when I'm off the keyboard, I love to travel a lot of places. I'm like a wanderlust kind of guy, you know, then I like to read some text stuff, be in touch with what's happening in the tech industry. And I keep experimenting with this weird stuff like this one and eventually speak in conferences about this. Yeah, so this is what we're going to be covering today.

So we'll start from why the problem exists and why we should and when we should actually invest in solving this. Then the technical depth, we'll see how this React DevTools actually work and we'll see how I built my own domain inspector. By domain inspector, I mean, you can consider that as a business logic. That's what I mean by domain. And then how we can keep it active, how we can keep it alive after you build it. You know, I think this is the most underrated part, but this is something we have to pay a lot of attention to. So let's get started.

The first thing React DevTools are enough. Yes, I repeat, React DevTools are actually enough, you know. And you may think what React DevTools are enough? You are sitting here on a Tuesday evening telling their React DevTools are enough in a custom React DevTools talk. I can hear you. But the thing is, React DevTools are an excellent tool. I want to tell this clearly before I spend the next 10 minutes describing what it doesn't do. The component inspector that it has, the profiler, the hooks panel, they're there really useful. The team that has built has put a lot of efforts in keeping it great today.

But meantime, React DevTools are not enough. When they are not enough and why they are not enough? See these tools were designed around a specific mental model of how the generic React application would look like. There will be components in a tree, props will be flowing down, states they will be living in hooks. The model is correct. And for most of the applications this should be enough. But is this a whole story for your application? Because when you have your business logic that lives outside your component tree, say you have your own state management tools, you have your own orchestration layers, you have your own workflow engines, React DevTools has nothing to say about it. It's not a quality gap also, because it was never built to do that. So I'll tell you some scenarios when we should actually invest in building our own dev tools. So the first one, I would call this as logging treadmill. Just like I did, you keep adding console logs for every 10 lines and debug the issue. I know this is a very obvious issue to solve an issue, like solve a bug. But the problem is, once in a while it is fine. If it's a very kind of issue that you cannot resolve in a single go, then I understand this is the only way. But if this keeps repeating a pattern, then building dev tools to improve your productivity is something that you should consider. And this scenario.

So the onboarding friction that doesn't go away. Like whenever someone gets into a new code base, the initial learning curve is normal. But we go to that senior person who is there to ask about the code base. And yeah, now we have AI also. But yeah, that's there. But if it keeps on happening over and over again, over time, then we need to have something that explains the business logic to us. There should be a system that explains the business logic to us. And if you're that senior who helps out the juniors, you know, in any issues, my respect for you. And yeah, when you have your own state management tool, when you choose to, you know, build your own stuff, your own things, then in that case, the React dev tools or some developer tools have no visibility over it. So we should invest in developing our custom dev tools there.

Then now we'll see how a React dev tools is actually built, right? So once you look at this scary diagram, I'm not going to explain you this deep React internal and all, but I strongly recommend pause here, take time to understand what's happening over here. But this mechanism React exposes for this is actually very simple. I'll tell you with the much simplified, you know, architecture. Then we'll look into the code of how I did it. So when your React app starts up before anything renders, it checks for a global variable on the window. And it is called react dev tools global hook. Yeah, React uses it as a communication channel. So every commit, every update, whatever you do, you know, every state changes, everything reacts actually streams this information through this hook only. And this is how the official React dev tools extension also works.

So they are pumped into an extension. And once you are in your dev tools, you will see a new, you know, new thing, a new panel called whatever they have, like they have components, they have profiler and a lot of Yeah, now here's the part that opens the door for us. This hook is not just an object on a window. There's nothing special about it, who puts it there, we can put our own listener on to it. That's that's a great part. So alongside the official dev tools, we work with React and not around it. So this architecture has four pieces basically. So we build our own custom inspector extension, we have our own logic there. Then in our UI, I'll see we'll see what this whatever we have built like yeah. So let's see how we can build this custom UI. Dev tools, I'll show you my code.

First, I wanted to say this is basically a white coded UI. This is a React app, this is a very simple React app that tried to reproduce the issue that I had in my, you know, in my eCommerce app. Right? So this is a white coded app, white coded kind of it's gonna look something like this. So this is a simple thing. And this is a dev tool extension. This is a very normal dev tool extension that we build with this manifest and all.

The main part over here is first, we have to check our state machine. So in my case, this store, this order orchestration store is my state manager. Yeah. So in this case, I will show you first this is like, this is a very normal state custom state state manager that I have built. These are just initializers. These are for subscriptions. These are to get the derived values. So basically, these stuff are like any AI can generate this.

So yeah, I'll show you one interesting method over here. I have a method called notify. And what this does, this pushes each every state snapshot to dev tools every time the state changes. So whenever the state is changing, we can actually look at that in live in our own dev tools. So I call this emit state snapshot. I'll show you where this works. So there's a dev tools bridge. So this is the heart of this application, I would say. So this is a kind of bridge that, you know, that should work only on dev environment. So you never ever forget to, you know, have it within your dev environment only. And for domain events, look at the process payments and all. So what happens is, right before, like, whenever this call finishes, I will show you my image state snapshot. Whenever this call finishes, we call this complete event with the side. Once we get that, that's the duration that we get the timeline. That's it.

That's it. And the census all the data, there's just one function one object, your state machine don't know anything about it, about your dev tools extension or not. It just emits an event into the bridge and moves on. That's it. So yeah.

And also I have a function. My domain, so there are a function to emit my domain ones as well. So this is kind of a bus of our thing, like our dev tools. So your domain code calls emit function and this content script called subscribe. Right? Yes, it will be here. Subscribe. Yeah.

This is the basically this bus of my application. They never actually talk to each other. The transport is windows.thisPostMessage. What this does, if the dev tools extension is opening and listening, it catches it. Even if it is not open, there is like nothing happens and no cost for us. So it's going to be efficient also. And this entire bridge, this is, you know, wrapped around this environment so that it is your users will never see it. And I will show you how I. Right.

This is the stuff. This is a function that sends this structured message to my dev tools panel. It does one thing. It listens to this window.PostMessage, catches messages from our bridge, and it forwards them to this current time send message to route them to the panel. The panel, the panel. This is again a wipe coded UI. This just catches every state and it gives me neat, neat and perfect, perfect thing. So this is the entire architecture. Now let's.

So if you look at here, this explains the simple architecture of our application works. So we have our on order payment, our own custom rules. Like our own state machine and all. This is getting emitted to this dev tool bridge which is a lightweight, even bus. And that post this message to this Chrome DevTools panel. So there are a lot of stuff you can do around this. Now let's look into the implementation.

So the first thing that you have to do, you have to, you know, unpack this extension. You just have to click, you just have to select it. As I've already done this, I'm not going to do it again. And this is what is here. This is DevTools like React DevTools official extension. So I opened my DevTools. So this is the components like the DevTools is showing. So we can see what this props works, what it is rendered by everything is being shown here, right? So everything is for me over here. Yeah. And I have this profiler as well. I'll start recording it. And the magical part, we have our own domain inspector that we built over here in this React in this Chrome DevTools panel. So I'm going to clear everything. I'm going to start this fresh.

So let's try to select a customer. I'll add this to me. So here's what you see. There is literally there is everything, right? But if we look at these components, you can see the product catalog, like the states, like the components, the props that are entering. And only that we can see. You can drill into the tree and see the values. But if we ask this question, is this order high risk? What phase is this order in? If payment fails, why does it fail? It can't answer any of those questions, not because it is broken because it was never built to answer them. Right.

Now we'll look into our domain inspector tab. So we have our things over here. So we have which state, which phase that we are in. It shows me literally every state of this, this thing. The raw business state, the cart contents, the customer details, the payment status. It is like not getting filtered through a component tree. This is the part I wanted you to notice. A standard dev tool shows you what's in the store, but R panels compute everything and surfaces derived states specifically for debugging, like pretty much everything is there. Right. I'll try to. Apply this. I'll proceed to payment.

Now, let's see. Let's see this event also. See, the thing is, here it is monitoring every each and every event with the timestamp. So when there is something going wrong, you can easily look at the timestamp and you can simply figure it out. So I'll try to pay. My payment is declined. Now that also is being logged here perfectly. Failure, reason, cart declined, everything, literally everything is there. So I'll tell you.

So I'll tell you. When some you know payment gets paid. We'll try for some different users now. I'll trigger an error. See. My domain context at the time of error, like when there was an error, how my state looked like. It failed in standard react setup, you'd be digging through network network tabs. You'll be trying through the request, reading raw API response, everything. But here. Here like. Even if you look at the event, you can like, you know, simply put the payments or debug stuffs like everything can be filtered and checked in real time.

So this. This thing over here is there. So this is what pretty much our react dev tools can do. So we'll go back to the slide. So we have our dev tools in action. Now the most important part, keeping it alive. Honestly, building this is really an easy part. Keeping it alive is where most internal tools are failing. So there is a few things that we have to keep in mind when we are taking this tool, you know, actually using this and keeping it alive.

The first thing is distribution. Don't put this stuff on your Chrome web store and all. You don't need to ship it. You don't need to have it with the things. Just commit the extension folder to your monorepo. That should be enough. Your engineers can load it. You can load it as an unpacked extension and your onboarding script can automate it. That step also. That's all done so that anyone they have their own dev tools, they can also modify them and you know, they can make it even better.

And there's production safety. This is non-negotiable. This bridge must do nothing in production. Like this one, we have to make sure very surely. It perfectly needs to be wrapped in only for dev environment so that it is not affecting your users.

And the third most important thing, there should be clear owners to it. This is the one that actually determines whether the tools last or not. So as a person, whenever a new domain events get added to the system, updating the panel is a part of acceptance criteria also. It's not going to be a follow-up task. It's not going to be, we'll do it later. So this is something that should be a non-negotiable also.

And very importantly, keeping it useful. Keep reviewing it. Every quarter spend at least 30 minutes with a couple of engineers who actually uses it. Is this really helping you? Is it really doing its job? If the panel is answering question people what they actually have, they'll use it. If it's answering question you thought you have six months ago, it'll gather dust only. So there is nothing going to be useful. So that's what I wanted to cover in this talk.