Overview

This guide integrates Vibenv into a Vue 3 application using Vite. The integration uses Vite plugins to inject the agent script, mount the Vibenv server routes, and add component metadata attributes to your Vue components.

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 dev dependencies

Install the required Vibenv packages:

npm install --save-dev @vibenv/vite-plugins @vibenv/framework-plugins

3) Configure Vite

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

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

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(() => {
  return {
    plugins: [
      vue(),
      agentEnvProviderVitePlugin(),
      viteVibeServer(),
      process.env.INCLUDE_VIBENV_AGENT === "true" && relativeAgentPlugin(),
      process.env.INCLUDE_VIBENV_AGENT !== "true" && devAgentPlugin(),
    ].filter(Boolean),
  }
})

What this does:

• agentEnvProviderVitePlugin() - Provides environment variables for the Vibenv agent
• viteVibeServer() - Mounts the Vibenv dev server routes onto the Vite dev server
• relativeAgentPlugin() - Injects the agent script at /vibeagent.js (used when INCLUDE_VIBENV_AGENT=true)
• devAgentPlugin() - Development agent plugin (used by default)

4) Add the Vue plugin to your app

In your src/main.js, register the Vue plugin to add component metadata:

import { createApp } from "vue"
import App from "./App.vue"
import VuePluginExtractFiles from "@vibenv/framework-plugins/vue-plugin-extract-files.js"

let app = createApp(App)
app.use(VuePluginExtractFiles)
app.mount("#app")

This plugin automatically adds the following attributes to your Vue component root elements:

• data-component-file - The file path of the component
• data-component-name - The name of the component

5) Run the dev server

npm run dev

You should see vibenv logs in the console during compilation, and the Vibenv overlay should connect once the page loads.

Optional: Set the CLI agent via .vibenv.js

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

module.exports = {
  "cli-agent": "claude" // or "copilot"
}

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

Optional: Environment variables

You can optionally create a .env file in your project root to configure Vibenv behavior:

# Use the relative agent plugin (serves agent from /vibeagent.js)
INCLUDE_VIBENV_AGENT=true

# Use the dev agent plugin (default behavior)
# INCLUDE_VIBENV_AGENT=false

Complete package.json example

{
  "name": "your-vue3-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.22"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.4",
    "vite": "^5.4.11",
    "@vibenv/vite-plugins": "workspace:^",
    "@vibenv/framework-plugins": "workspace:^"
  }
}

Notes

• Vue 3 projects do not require a transpiler plugin (Babel/SWC) because the vue-plugin-extract-files plugin handles metadata injection directly
• The agent script is served at /vibeagent.js by default
• dotenv reads from .env in the project root so you can override Vibenv environment variables locally
• Ensure your Node.js version meets the requirements (Node.js >=22 is recommended for Vue 3 + Vite)