> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ladybugs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Guide

> Get started with Ladybugs in your local project

## 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.

<Warning>
  **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.
</Warning>

## Quick Start

<Steps>
  <Step title="Start the Docker container">
    Run the Ladybugs collection server on port 4866:

    ```bash theme={null}
    docker run -p 4866:3000 ladybugsio/collection-server:latest
    ```
  </Step>

  <Step title="Build/run your project with Ladybugs CLI">
    Use the `@ladybugs/cli` tool to instrument and run your project (see options below).
  </Step>

  <Step title="Reproduce the bug">
    Interact with your application to trigger the bug you want to debug.
  </Step>

  <Step title="Debug with AI + MCP">
    Use the [MCP integration](/mcp/setup) through your favorite AI tool to automatically investigate and fix the bug.
  </Step>

  <Step title="Clean up">
    Remove the Docker container to free up space:

    ```bash theme={null}
    docker stop $(docker ps -q --filter ancestor=ladybugsio/collection-server:latest)
    docker rm $(docker ps -aq --filter ancestor=ladybugsio/collection-server:latest)
    ```

    <Note>Currently, collected data is not cleaned automatically, so remember to remove the container when done.</Note>
  </Step>
</Steps>

***

## 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:

```bash theme={null}
npx @ladybugs/cli run src/index.js --import-type=import
```

Or for CommonJS projects:

```bash theme={null}
npx @ladybugs/cli run src/index.ts --import-type=require
```

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

**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):

```bash theme={null}
npx @ladybugs/cli run ./index.html
```

<Info>
  The CLI automatically detects your frontend framework and handles the instrumentation.
</Info>

### Build-Only Mode

If you want to build without immediately running:

```bash theme={null}
# 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.

<Tabs>
  <Tab title="Babel Config">
    Add the plugin to your `babel.config.js` or `.babelrc`:

    ```javascript theme={null}
    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...
      ]
    }
    ```

    <Warning>
      If using TypeScript, add the Ladybugs plugin **after** any TypeScript parsing plugins but **before** other transformations.
    </Warning>
  </Tab>

  <Tab title="Vite Config">
    For Vite projects, add the plugin to `vite.config.js`:

    ```javascript theme={null}
    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
          }
        }
      ]
    })
    ```
  </Tab>
</Tabs>

### Include the SDK

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

```html theme={null}
<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:

```bash theme={null}
ENV_TYPE=browser npx @ladybugs/cli run ./index.html
```

This helps Ladybugs correctly identify the runtime environment.

***

## Important Limitations

<CardGroup cols={2}>
  <Card title="Production builds only" icon="hammer">
    Ladybugs requires a **full production build**. It won't work reliably with:

    * Watch mode (`--watch`)
    * Development servers (`dev` mode)
    * Hot module replacement (HMR)
  </Card>

  <Card title="Supported frameworks" icon="code">
    Currently supported:

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

    More frameworks coming soon!
  </Card>
</CardGroup>

***

## Troubleshooting

### Docker container won't start

Make sure port 4866 is not already in use:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="TypeScript compilation errors">
    Ensure the Ladybugs Babel plugin is added **after** TypeScript parsing plugins in your Babel config.
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

### Can't connect to collection server

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

1. Verify the container is running: `docker ps | grep ladybugsio/collection-server`
2. Check Docker logs: `docker logs $(docker ps -q --filter ancestor=ladybugsio/collection-server:latest)`
3. Ensure no firewall is blocking port 4866
4. Contact Ladybugs support at [support@ladybugs.io](mailto:support@ladybugs.io)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug" href="/mcp/setup">
    Connect Ladybugs to your AI assistant to start debugging with AI
  </Card>

  <Card title="How It Works" icon="gears" href="/guides/how-it-works">
    Understand the technical details behind Ladybugs
  </Card>
</CardGroup>