Setup Guide

Overview

Ladybugs helps you debug production issues by capturing complete runtime context. This guide will walk you through setting up Ladybugs for your JavaScript/TypeScript project.

Use Ladybugs only when debugging! We recommend not leaving the container running for long periods. Start it when you need to debug, then remove it when done.

Quick Start

Start the Docker container

Run the Ladybugs collection server on port 4866:

docker run -p 4866:3000 ladybugsio/collection-server:latest

Build/run your project with Ladybugs CLI

Use the @ladybugs/cli tool to instrument and run your project (see options below).

Reproduce the bug

Interact with your application to trigger the bug you want to debug.

Debug with AI + MCP

Use the MCP integration through your favorite AI tool to automatically investigate and fix the bug.

Clean up

Remove the Docker container to free up space:

docker stop $(docker ps -q --filter ancestor=ladybugsio/collection-server:latest)
docker rm $(docker ps -aq --filter ancestor=ladybugsio/collection-server:latest)

Currently, collected data is not cleaned automatically, so remember to remove the container when done.

Using the CLI Tool

The @ladybugs/cli tool automatically instruments your code with the Babel plugin and handles the build process.

Backend Projects & Standalone Scripts

For Node.js applications or standalone JavaScript/TypeScript files:

npx @ladybugs/cli run src/index.js --import-type=import

Or for CommonJS projects:

npx @ladybugs/cli run src/index.ts --import-type=require

Always specify --import-type! Omitting this flag may cause the CLI to incorrectly detect your module system, leading to unexpected behavior.

Supported import types:

--import-type=import - For ES modules (import/export)
--import-type=require - For CommonJS (require/module.exports)

Frontend Projects

For frontend applications (currently supports vanilla JS and Vite + React):

npx @ladybugs/cli run ./index.html

The CLI automatically detects your frontend framework and handles the instrumentation.

Build-Only Mode

If you want to build without immediately running:

# Backend
npx @ladybugs/cli build src/index.js --import-type=import

# Frontend
npx @ladybugs/cli build ./index.html

Advanced Usage

Manual Babel Configuration

For more control, you can manually integrate the @ladybugs/babel-plugin-debug into your existing build configuration.

Babel Config
Vite Config

Add the plugin to your babel.config.js or .babelrc:

module.exports = {
  plugins: [
    // TypeScript parsing (if using TypeScript)
    '@babel/plugin-syntax-typescript',

    // Add Ladybugs plugin after TypeScript, before other transforms
    '@ladybugs/babel-plugin-debug',

    // Your other plugins...
  ]
}

If using TypeScript, add the Ladybugs plugin after any TypeScript parsing plugins but before other transformations.

For Vite projects, add the plugin to vite.config.js:

import { defineConfig } from 'vite'
import ladybugsPlugin from '@ladybugs/babel-plugin-debug'

export default defineConfig({
  plugins: [
    {
      name: 'ladybugs-babel',
      transform(code, id) {
        if (!/\.(jsx?|tsx?)$/.test(id)) return null

        // Apply Babel transformation with Ladybugs plugin
        const result = babel.transform(code, {
          plugins: [ladybugsPlugin],
          filename: id,
        })

        return result
      }
    }
  ]
})

Include the SDK

When using manual configuration, you must include the Ladybugs SDK in your HTML:

<script src="https://unpkg.com/@ladybugs/sdk/dist/ladybugs.min.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/@ladybugs/sdk/dist/ladybugs.min.js"></script>

Environment Variables

For client-side production builds, you may need to set:

ENV_TYPE=browser npx @ladybugs/cli run ./index.html

This helps Ladybugs correctly identify the runtime environment.

Important Limitations

Production builds only

Ladybugs requires a full production build. It won’t work reliably with:

Watch mode (--watch)
Development servers (dev mode)
Hot module replacement (HMR)

Supported frameworks

Currently supported:

Node.js (any version)
Vanilla JavaScript
Vite + React

More frameworks coming soon!

Troubleshooting

Docker container won’t start

Make sure port 4866 is not already in use:

# Check if port is in use
netstat -an | grep 4866

# Kill process using the port (if needed)
lsof -ti:4866 | xargs kill -9

CLI tool errors

Module import errors

Always use --import-type flag to specify your module system:

Use --import-type=import for ES modules
Use --import-type=require for CommonJS

TypeScript compilation errors

Ensure the Ladybugs Babel plugin is added after TypeScript parsing plugins in your Babel config.

Build succeeds but no data collected

Verify the Docker container is running: docker ps
Check that your app can reach http://localhost:4866
For frontend builds, ensure the SDK script is included in your HTML
For client builds, try setting ENV_TYPE=browser

Can’t connect to collection server

If your application can’t send data to the Docker container:

Verify the container is running: docker ps | grep ladybugsio/collection-server
Check Docker logs: docker logs $(docker ps -q --filter ancestor=ladybugsio/collection-server:latest)
Ensure no firewall is blocking port 4866
Contact Ladybugs support at [email protected]

Getting Started

MCP Integration

Guides

Overview

Quick Start

Using the CLI Tool

Backend Projects & Standalone Scripts

Frontend Projects

Build-Only Mode

Advanced Usage

Manual Babel Configuration

Include the SDK

Environment Variables

Important Limitations

Production builds only

Supported frameworks

Troubleshooting

Docker container won’t start

CLI tool errors

Can’t connect to collection server

Next Steps

MCP Integration

How It Works

Getting Started

MCP Integration

Guides

​Overview

​Quick Start

​Using the CLI Tool

​Backend Projects & Standalone Scripts

​Frontend Projects

​Build-Only Mode

​Advanced Usage

​Manual Babel Configuration

​Include the SDK

​Environment Variables

​Important Limitations

Production builds only

Supported frameworks

​Troubleshooting

​Docker container won’t start

​CLI tool errors

​Can’t connect to collection server

​Next Steps

MCP Integration

How It Works

Overview

Quick Start

Using the CLI Tool

Backend Projects & Standalone Scripts

Frontend Projects

Build-Only Mode

Advanced Usage

Manual Babel Configuration

Include the SDK

Environment Variables

Important Limitations

Troubleshooting

Docker container won’t start

CLI tool errors

Can’t connect to collection server

Next Steps