Vite Configuration for AI Agents

Overview

When configuring Vite for use with AI agents (agent-browser, Playwright, or other automated browser tools), set server.open: false to prevent the development server from automatically opening browser windows during agent automation.

Agent Browser Configuration

Critical: If the agent is using agent-browser or other agent browser tools, the Vite config must set server.open: false to prevent the server from continually opening browser windows.

Example Configuration

import { defineConfig } from "vite";

export default defineConfig({
  root: ".",
  build: {
    outDir: "dist",
    sourcemap: true,
  },
  server: {
    port: 3000,
    open: false, // Required for agent browsers
  },
  resolve: {
    alias: {
      "@": "/src",
    },
  },
});

OS-Agnostic Configuration

For consistent agent automation across different operating systems, use OS-agnostic settings and avoid platform-specific commands.

Required Server Settings

server: {
  port: 3000,
  strictPort: true, // Required: fail fast if port occupied
  open: false // Required for agent browsers
}

Why strictPort: true is critical:

• •Prevents "port hunting" behavior where Vite tries multiple ports
• •Fails fast if the port is occupied, making issues immediately visible
• •Essential for consistent agent automation that expects a specific port
• •Without it, agents may connect to the wrong port or wait indefinitely

Avoiding OS-Specific Commands

When writing scripts or automation that works with Vite:

• •❌ Don't use: GNU-specific timeout command (Linux-only)
• •✅ Do use: Node-based scripts or OS-agnostic alternatives
• •✅ Example: Use wait-on package instead of shell timeout:
  bash

  npm install -D wait-on
  # In package.json:
  "scripts": {
    "wait-for-dev": "wait-on http://localhost:3000"
  }
  

Key Points

• •server.open: false - Prevents automatic browser opening, essential for agent automation
• •server.port - Specify a port for consistent agent access
• •server.strictPort: true - Fail fast if port is occupied, prevents port hunting
• •build.sourcemap: true - Helpful for debugging agent interactions
• •Path aliases - Configure as needed for the project structure

Port Configuration

Default port: 5173

This project uses port 3000 - check vite.config.ts for actual port configuration.

Always verify actual port before browser connection:

• •Check vite.config.ts for server.port configuration
• •Check package.json for PORT environment variable
• •Don't assume default ports (3000, 5173, etc.)

Port Detection Patterns

Reference: See dev-server-port-detection skill for comprehensive port discovery patterns.

Standard workflow:

1. •Check vite.config.ts for server.port configuration
2. •Check package.json for PORT environment variable
3. •Check running processes or terminal output for actual port
4. •Use discovered port in browser commands

Pattern:

# Check vite.config.ts
grep -A 5 "server:" vite.config.ts

# Check package.json
grep -i "port" package.json

# Check running processes
lsof -i :3000 || lsof -i :5173

Port Conflict Resolution

If port is occupied:

1. •Check what process is using the port
2. •Kill the process if it's an old dev server
3. •Or use a different port in vite.config.ts

Pattern:

# Find process using port
lsof -i :3000

# Kill process (if it's an old dev server)
kill -9 <PID>

Server Health Check Utilities

Poll server until ready:

# Wait for server to be ready
for i in {1..10}; do
  if curl -s http://localhost:3000 > /dev/null; then break; fi
  sleep 2
done

Check server health endpoint (if available):

curl http://localhost:3000/health

Server Startup Verification Patterns

Wait for "Local:" message in terminal output before proceeding with browser testing.

Pattern:

# Start server
npm run dev &

# Wait for server ready message
# Look for "Local: http://localhost:3000" in output

Implement retry logic with timeout (max 30 seconds):

TIMEOUT=30
ELAPSED=0
while [ $ELAPSED -lt $TIMEOUT ]; do
  if curl -s http://localhost:3000 > /dev/null; then
    echo "Server is ready"
    break
  fi
  sleep 2
  ELAPSED=$((ELAPSED + 2))
done

Server Readiness

Don't assume server is ready after npm run dev

Poll server health endpoint until ready:

# Wait for server to be ready
for i in {1..10}; do
  if curl -s http://localhost:3000 > /dev/null; then break; fi
  sleep 2
done

Wait for "Local:" message in terminal output before proceeding with browser testing.

Implement retry logic with timeout (max 30 seconds).

When to Apply

Always set server.open: false when:

• •Using agent-browser for automation
• •Using Playwright or other headless browser tools
• •Running Vite in CI/CD environments
• •Any scenario where automatic browser opening would interfere with agent workflows