Joaninha Da Ladybug

What joaninha da ladybug actually does

It is a visual debugging and log-monitoring utility for JavaScript and TypeScript projects, built on an electron shell with a websocket-based data pipeline. You run it locally, point it at your dev server, and it pulls structured events from your application in real time. That is the baseline. Everything else is noise unless you understand how it captures data under load.

Installing and configuring joaninha da ladybug

The installation itself is trivial. Clone the repo or pull the latest release from npm if they publish there. Run the build script, then execute the binary. The first time you start it, it opens a config dialog that asks for your API endpoint or local dev URL. Most people connect it to localhost:3000 and move on. That works fine for a basic setup. The actual configuration lives in a YAML file at ~/.joaninha/config.yaml, and that is where you will spend most of your time after the initial setup. Here is what you need to adjust: the port it listens on for incoming events (default is 8765), the buffer size for log retention (default is 10,000 entries before it starts dropping older ones), and the auto-disconnect delay. By default it drops the connection after four minutes of inactivity. If you are doing long debugging sessions where you step through code and then go grab coffee, that setting will kill your session unexpectedly. I changed mine to thirty minutes and have not had an issue since.

How it works under the hood

Most people assume joaninha da ladybug intercepts console output by monkey-patching the global console object. It does not. That approach is fragile and breaks as soon as your code uses a logger library like winston or pino. Instead it injects a custom EventTarget into the DOM when the integration script loads, and your application sends structured payloads to it via fetch or a shared websocket. The payloads are serialized as JSON and streamed through the integration layer into the local dashboard. The key detail beginners miss is that the integration must be loaded before any application code runs. If you load it after your framework initializes, you will capture events but you will miss the initial render cycle and any synchronous errors that happen during bootstrap. Put the script tag in the head section of your index.html, not in the body, and make sure your bundler does not tree-shake it away. I spent two days troubleshooting missing early-log events before I realized my Webpack config was stripping the integration module because it saw no static references to it. Adding it to the external list in the webpack config fixed it immediately.

Common problems and what actually fixes them

There are three issues that come up constantly, and none of them are documented clearly in the readme. First: port conflicts. The default listen port 8765 overlaps with several development tools. If you already run a GraphQL playground or a hot-reload server on that port, joaninha will refuse to start with a silent exit code 1. Check your other running services first. Use netstat or lsof to see what is occupying the port, then override it in the config file with the listen_port directive.

Second: large payload throttling. By default the integration batches events and only sends them every 500 milliseconds. This is fine for normal usage but catastrophic if you are debugging a rapid-fire event loop or a WebSocket-heavy feature. I encountered this when a client had a component that dispatched fifty state updates per second during a drag operation. The dashboard showed only two or three events total, making it look like the component was broken when it was actually working perfectly. Setting batch_interval_ms to 50 in the config resolved the visibility issue. CPU usage went up slightly, but the tradeoff was worth it for the diagnostic clarity. Third: CORS when your frontend and backend are on different origins. If you are developing a micro-frontend architecture where the UI runs on localhost:4200 and the API runs on localhost:8080, the integration script will be blocked from sending events by CORS policies. The fix is not to disable CORS globally. It is to configure your API server to accept POST requests to the joaninha websocket endpoint with the proper origin headers. Add a middleware route that forwards the events through without parsing them. This kept my security posture intact while letting the debugger function normally.

What it cannot do

Be honest about the limitations before you integrate it into a production pipeline. joaninha da ladybug is not a production monitoring tool. It has no alerting system, no retention longer than a few hours without manual export, and no team collaboration features. If you need incident response or on-call notifications, look at Datadog, New Relic, or even Sentry. The integration also does not track server-side logs natively. You have to wire up a separate agent for that, and the documentation for the server-side SDK is incomplete. I tried to use it to debug a Node.js background job that was failing intermittently, and the lack of server-side instrumentation meant I was blind to half the problem. A simple Pino transporter would have saved me four hours. Performance overhead is another factor. Under heavy event loads with the batch interval reduced, the integration script adds roughly fifteen to twenty percent CPU overhead to the main thread. Your application will feel sluggish in the dev environment. This is not a dealbreaker, but if you are profiling performance bottlenecks, turn joaninha off first and then back on so you can measure the delta accurately. The dashboard has a toggle for that, but the setting is buried in the settings menu behind two submenus.

When to skip it entirely

If your project is a simple static site with no client-side state management and no network activity, this tool adds zero value. The overhead is not worth the configuration effort. If you are using React DevTools or Vue DevTools as your primary debugging interface, joaninha overlaps with their capabilities and extends them only if you need structured log correlation across multiple services. In that case it makes sense. Otherwise you are solving a problem you do not have. For most single-page applications with moderate complexity, installing joaninha da ladybug takes about ten minutes end-to-end. The config file is the only place you might get stuck, and the port conflict issue is the only real blocker that requires external investigation. After that it runs silently in the background and you access it through the dashboard at localhost:3001 by default. That is the whole thing.