Vite Plugin Vue DevTools

Common errors

• Error: [vite-plugin-vue-devtools] The plugin function must return a plugin object.

  cause The `VueDevTools` function was imported but not called as a function (e.g., `VueDevTools` instead of `VueDevTools()`) in the `plugins` array.
  fix Call the plugin function in your `vite.config.ts`: ```typescript plugins: [ VueDevTools(), // Corrected: call the function vue(), ], ```

• Error: Cannot find module 'vite-plugin-vue-devtools'

  cause The package was not installed, or the import path is incorrect, or an ESM-only package is being imported in a CommonJS context.
  fix Ensure the package is installed as a dev dependency: `npm install -D vite-plugin-vue-devtools` or `yarn add -D vite-plugin-vue-devtools`. Verify the import statement `import VueDevTools from 'vite-plugin-vue-devtools'` is correct in your `vite.config.ts`.

• Vue DevTools (vite plugin) doesn't render as expected

  cause Often related to conflicts with other Vite plugins, particularly those that manipulate HTML, or incorrect plugin order.
  fix If you are using `vite-plugin-html`, ensure `vite-plugin-vue-devtools` is registered before `vite-plugin-html` in your `vite.config.ts`. Also, check the official troubleshooting guide.

• Plugin fails when remote bindings are enabled (e.g., Cloudflare Workers D1)

  cause There can be compatibility issues with `vite-plugin-vue-devtools` when specific build configurations, like remote bindings for databases (e.g., Cloudflare D1), are enabled, potentially due to how the plugin interacts with the HMR system.
  fix This is a known issue (e.g., Cloudflare Workers issue #11063). A temporary workaround might be to disable `vite-plugin-vue-devtools` during development with such configurations, or monitor the respective GitHub issues for updates and patches.

Warnings

• breaking Vue DevTools v7+ (and thus `vite-plugin-vue-devtools` v7+) exclusively supports Vue 3 applications. Projects using Vue 2 must use older versions of Vue DevTools (v6).
  Fix: For Vue 2 projects, install `vite-plugin-vue-devtools` v6 or directly use the browser extension for Vue DevTools v6. Ensure your `package.json` specifies compatible versions.
• gotcha Multiple `vite-plugin-vue-devtools` versions (v7.7.8, v7.7.9, v8.0.3, v8.0.4) addressed compatibility issues with Node.js v25+. Older versions might encounter problems when running on newer Node.js environments.
  Fix: Ensure you are using `vite-plugin-vue-devtools` version 8.0.4 or higher if you are developing with Node.js v25 or newer to avoid compatibility issues.
• breaking Version 8.0.2 included a security fix that removed a vulnerable, unmaintained `ip` package dependency. Users on older versions might be exposed to potential security vulnerabilities.
  Fix: Upgrade to `vite-plugin-vue-devtools` version 8.0.2 or newer immediately to mitigate the security vulnerability associated with the `ip` package.
• gotcha When combining `vite-plugin-vue-devtools` with other Vite plugins that modify HTML, such as `vite-plugin-html`, the order of plugins can matter. Incorrect ordering may prevent DevTools from rendering as expected.
  Fix: If using `vite-plugin-html` or similar, ensure `vite-plugin-vue-devtools` is registered *before* `vite-plugin-html` in your `vite.config.ts` plugins array.
• breaking The plugin has a peer dependency on `vite` (currently `^6.0.0 || ^7.0.0 || ^8.0.0`). Incompatible Vite versions will lead to installation or runtime errors.
  Fix: Ensure your project's `vite` dependency satisfies the peer dependency range specified by `vite-plugin-vue-devtools`. Update or downgrade Vite if necessary.

Install

• npm install vite-plugin-vue-devtools npm
• yarn add vite-plugin-vue-devtools yarn
• pnpm add vite-plugin-vue-devtools pnpm

Imports

• VueDevTools
  wrong:

  import { VueDevTools } from 'vite-plugin-vue-devtools'

  correct:

  import VueDevTools from 'vite-plugin-vue-devtools'

  The plugin is exported as a default function; it should not be destructured.
• defineConfig
  wrong:

  const defineConfig = require('vite')

  correct:

  import { defineConfig } from 'vite'

  Vite configuration files are typically ESM-first; use ES module imports.
• VueDevTools options

  import VueDevTools from 'vite-plugin-vue-devtools';
  export default defineConfig({
    plugins: [
      VueDevTools({
        componentInspector: false // Example option
      }),
    ],
  })

  The `VueDevTools` function can accept an options object to customize its behavior, such as disabling the component inspector. Refer to the official documentation for available options.

Quickstart

This quickstart demonstrates how to integrate `vite-plugin-vue-devtools` into a Vite configuration for a Vue 3 project, enabling the DevTools overlay in development mode. It also includes the standard `@vitejs/plugin-vue` plugin for completeness.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import VueDevTools from 'vite-plugin-vue-devtools'

export default defineConfig({
  plugins: [
    vue(),
    VueDevTools(),
  ],
  // Ensure your Vite project is configured for Vue 3
  // For example, if using TypeScript, ensure 'vue' is correctly resolved
  // Example of an environment variable usage (if applicable for other plugins):
  // server: {
  //   port: parseInt(process.env.PORT ?? '5173')
  // }
})