Overview

This guide demonstrates how to integrate Vibenv into a Vue 3 application using Vite as the bundler. The example application is a cryptocurrency dashboard that showcases real-time data visualization, but the integration steps apply to any Vue 3 + Vite project.

The integration uses Vite plugins to:

• Mount the Vibenv server routes on the development server
• Inject the agent script into your HTML
• Provide environment variables for the agent

Prerequisites

Before integrating Vibenv, ensure you have:

• Node.js 20+ installed
• Vue 3.4+ project using Vite 5+
• TypeScript 5.4+ (recommended but not required)
• npm or yarn package manager
• Vibenv registry credentials (contact the Vibenv team)

1) Configure .npmrc for Vibenv Packages

Vibenv ships as scoped packages from the Vibenv registry. Add this to your project-level .npmrc:

@vibenv:registry=https://npm.vibenv.net/

Then authenticate with the Vibenv registry:

npm login --scope @vibenv

Login details will be provided by the Vibenv team.

2) Install Dependencies

Install the required Vibenv packages as dependencies:

npm install @vibenv/vite-plugins @vibenv/framework-plugins @vibenv/constants @vibenv/logger @vibenv/platform @vibenv/transpiler-plugins @vibenv/vibe-agent @vibenv/vibe-server

3) Configure vite.config.ts

Update your vite.config.ts to include the Vibenv plugins:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig, type PluginOption } from 'vite'
import vue from '@vitejs/plugin-vue'

// Import Vibenv plugins
import { agentEnvProviderVitePlugin } from "@vibenv/vite-plugins/agent-env-provider-vite-plugin.js"
import { viteVibeServer } from "@vibenv/vite-plugins/vite-vibe-server.js"
import { relativeAgentPlugin } from "@vibenv/vite-plugins/relative-agent-plugin.js"
import { devAgentPlugin } from "@vibenv/vite-plugins/dev-agent-plugin.js"

export default defineConfig({
  server: {
    port: 8080  // Your preferred port
  },
  plugins: [
    vue(),
    // Vibenv plugins
    agentEnvProviderVitePlugin() as PluginOption,
    viteVibeServer() as PluginOption,
    devAgentPlugin() as PluginOption
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  // Additional Vite configuration...
})

Plugin Overview

Plugin	Purpose
agentEnvProviderVitePlugin()	Defines __PROJECT_ROOT__ global constant for the agent
viteVibeServer()	Mounts Vibenv Express server at /_vibe-agent routes
devAgentPlugin()	Injects agent script during development
relativeAgentPlugin()	(Alternative) Injects agent at custom path like /vibeagent.js

4) Add Vue Framework Plugin (Optional)

For Vue 3 applications, you can add the Vue-specific plugin that automatically extracts file metadata from components:

Create or update your main application entry point (e.g., src/main.ts):

import { createApp } from 'vue'
import App from './App.vue'
import { createRouter } from './router'
import { createPinia } from 'pinia'

// Import Vibenv Vue plugin
import VuePluginExtractFiles from "@vibenv/framework-plugins/vue-plugin-extract-files.js"

const app = createApp(App)

// Install the Vibenv plugin
app.use(VuePluginExtractFiles)

app.use(createRouter())
app.use(createPinia())

app.mount('#app')

This plugin automatically adds these data attributes to Vue component root elements:

• data-component-file - Absolute path to the component file
• data-component-name - Component name

These attributes enable the Vibenv agent to identify and interact with your components.

5) Update package.json Scripts

Ensure your package.json has the following scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

6) Run the Development Server

Start your development server:

npm run dev

You should see:

• Your Vite dev server starting on port 8080 (or your configured port)
• Vibenv server mounting at /_vibe-agent
• The Vibenv agent connecting to your application

Optional: Set the CLI Agent via .vibenv.js

Create .vibenv.js in your project root to control which CLI agent Vibenv uses:

export default {
  "cli-agent": "claude"  // or "copilot"
}

This file is read from the current working directory when Vibenv starts.

Additional Configuration Options

The .vibenv.js file supports additional configuration:

export default {
  "cli-agent": "claude",           // Which AI agent to use
  "accept-strategy": {              // How to accept changes (future feature)
    "type": "gitlab-pr",
    "options": {
      "targetBranch": "main",
      "removeSourceBranch": true
    }
  }
}

Example: Vue 3 Crypto Dashboard

The example at examples/sample-vue3-crypto-dashboard demonstrates a complete integration with:

• Real-time cryptocurrency data via Binance WebSocket API
• amCharts5 for historical price charts
• Custom sparkline charts implemented in Vue
• Bootstrap 5 for styling
• Pinia for state management
• Vue Router 4 for navigation
• TypeScript for type safety

Key Features from the Example

// vite.config.ts from the example
import { agentEnvProviderVitePlugin } from "@vibenv/vite-plugins/agent-env-provider-vite-plugin.js"
import { viteVibeServer } from "@vibenv/vite-plugins/vite-vibe-server.js"
import { relativeAgentPlugin } from "@vibenv/vite-plugins/relative-agent-plugin.js"
import { devAgentPlugin } from "@vibenv/vite-plugins/dev-agent-plugin.js"

export default defineConfig({
  server: {
    port: 8080
  },
  plugins: [
    vue(),
    agentEnvProviderVitePlugin() as PluginOption,
    viteVibeServer() as PluginOption,
    devAgentPlugin() as PluginOption
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        silenceDeprecations: ['mixed-decls', 'color-functions', 'global-builtin', 'import']
      }
    }
  }
})

Troubleshooting

Agent Not Connecting

If the Vibenv agent overlay doesn't appear:

1. Check browser console for errors
2. Verify plugins are loaded - you should see Vibenv logs in your terminal
3. Ensure port is available - the default Vite port should not conflict with Vibenv server (port 5005)
4. Check .npmrc - ensure the registry is configured correctly

Module Resolution Errors

If you see errors importing Vibenv packages:

1. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install

2. Verify package paths - imports should use .js extensions even for TypeScript files:

   import { viteVibeServer } from "@vibenv/vite-plugins/vite-vibe-server.js"

TypeScript Errors

If TypeScript reports errors with Vibenv packages:

1. Check tsconfig.json includes node_modules/@vibenv in compiler options
2. Restart your IDE - sometimes TypeScript cache needs clearing
3. Run type check:

   npm run type-check

Production Builds

Vibenv plugins only run during development. For production builds:

npm run build

The agent script and server routes are not included in production bundles, ensuring optimal performance in deployed applications.

Next Steps

• Explore Core Concepts - Learn about Vibenv architecture
• Configuration System - Understand configuration options
• Server API - Reference for server endpoints
• Advanced Integration - Custom integrations and plugins

Related Integrations

• Angular 19 (Webpack) - Angular with webpack dev server
• Framework-Specific Guide - All framework integrations