Integration Guide

Integration Guide

Complete guide to integrating DevMirror into your development workflow.

Integration Strategies

1. Simple Integration (Default)

Best for new projects without existing logging.

"dev:mirror": "concurrently \"npx devmirror-cli\" \"npm run dev\""

• DevMirror runs alongside your dev server
• All console output captured
• No interference with existing tools

2. Companion Mode

For projects with existing loggers (like CEF logger).

"dev:mirror": "npm run dev & npx devmirror-companion"

Note: Use devmirror-companion script for non-invasive operation alongside existing tools.

• Preserves existing logger functionality
• DevMirror captures additional output
• No conflicts with current setup

3. Port Auto-Detection

For applications with varying ports.

devmirror.config.json:

{
  "autoDetectPort": true,
  "url": "http://localhost:3000"
}

• Automatically detects running dev server ports
• Waits for target application to be ready
• Configurable via DevMirror configuration

4. Background Mode

For complex interactive environments.

scripts/devmirror-background.js:

import { spawn } from 'child_process';
import net from 'net';

function checkPort(port) {
    return new Promise((resolve) => {
        const socket = net.createConnection(port, 'localhost');
        socket.on('connect', () => {
            socket.destroy();
            resolve(true);
        });
        socket.on('error', () => resolve(false));
    });
}

async function waitForPort() {
    while (true) {
        if (await checkPort(8555)) {
            console.log('Port detected! Starting DevMirror...');
            return true;
        }
        await new Promise(r => setTimeout(r, 1000));
    }
}

async function start() {
    await waitForPort();
    spawn('npx', ['devmirror-cli'], {
        stdio: ['ignore', 'ignore', 'inherit'],
        env: { ...process.env, DEVMIRROR_SILENT: 'true' }
    });
}

start().catch(console.error);

Framework-Specific Integration

React (Create React App)

{
  "scripts": {
    "start:mirror": "concurrently \"npx devmirror-cli\" \"react-scripts start\""
  }
}

Vue (Vite)

{
  "scripts": {
    "dev:mirror": "concurrently \"npx devmirror-cli\" \"vite\""
  }
}

Angular

{
  "scripts": {
    "start:mirror": "concurrently \"npx devmirror-cli\" \"ng serve\""
  }
}

Next.js

{
  "scripts": {
    "dev:mirror": "concurrently \"npx devmirror-cli\" \"next dev\""
  }
}

Note: Configure specific ports and other options in devmirror.config.json rather than using CLI flags.

Build Tool Integration

Webpack

// webpack.config.js
module.exports = {
  devServer: {
    port: 8080,
    onListening: function(devServer) {
      // DevMirror will connect when port is ready
      console.log('Webpack dev server ready on port:', devServer.port);
    }
  }
};

Vite

// vite.config.js
export default {
  server: {
    port: 5173,
    open: true
  }
};

Parcel

{
  "scripts": {
    "dev:mirror": "concurrently \"npx devmirror-cli\" \"parcel index.html\""
  }
}

CI/CD Integration

GitHub Actions

- name: Run tests with DevMirror
  run: |
    npm run test:mirror
  env:
    DEVMIRROR_OUTPUT: ./test-logs

Jenkins

stage('Dev with logging') {
    steps {
        sh 'npm run dev:mirror'
        archiveArtifacts 'devmirror-logs/**/*.log'
    }
}

Docker Integration

docker-compose.yml:

services:
  app:
    build: .
    ports:
      - "3000:3000"
      - "9222:9222"  # Chrome DevTools
    environment:
      - DEVMIRROR_PORT=9222
    command: npm run dev:mirror

Environment Variables

These are supported by the companion script:

export DEVMIRROR_ENABLE=true
export DEVMIRROR_MODE=auto
export DEVMIRROR_OUTPUT=./devmirror-logs
export DEVMIRROR_CEF_PORT=8555
export DEVMIRROR_URL=http://localhost:3000
export DEVMIRROR_PARALLEL=true
export DEVMIRROR_SILENT=false

Note: The main CLI (devmirror-cli) uses configuration files, not environment variables.

Conditional Integration

Only run DevMirror in development:

{
  "scripts": {
    "dev": "NODE_ENV=development npm run dev:mirror || npm run dev:normal"
  }
}

Multiple Environments

package.json:

{
  "scripts": {
    "dev:local": "npx devmirror-cli --config=local.config.json",
    "dev:staging": "npx devmirror-cli --config=staging.config.json",
    "dev:test": "npx devmirror-cli --config=test.config.json"
  }
}

Debugging Integration Issues

1. Test connection manually:

curl http://localhost:9222/json

2. Check if port is open:

lsof -i :9222

3. Check VS Code Output:

View → Output → DevMirror

4. Direct CLI test:

npx devmirror-cli --config=devmirror.config.json

Best Practices

1. Always use specific ports instead of auto-detection in production workflows
2. Set appropriate timeouts for slow-starting applications
3. Use companion mode when you have existing loggers
4. Enable reconnect for hot-reloading dev servers
5. Clean up logs periodically to save disk space
6. Use environment-specific configs for different setups
7. Document your setup in README for team members

Troubleshooting Integration

DevMirror starts too early

• Use wait mode with port detection
• Increase timeout value
• Add startup delay in script

Conflicts with existing tools

• Use companion mode
• Run on different port
• Use background script approach

Performance issues

• Reduce throttle settings in config
• Use smaller output buffer size
• Disable in production builds

Port conflicts

• Use custom ports
• Check for processes using ports
• Use port ranges for auto-detection