vite-plugin-vconsole

2.1.1 verified Mon Apr 27 auth: no javascript

Vite plugin for automatically injecting vConsole (a lightweight, extendable front-end developer tool for mobile web pages) into your application during development or specific build modes. Current stable version is 2.1.1, released in 2023. It supports Vite v2+, Node.js >=12, and works with both Vue and React. Key differentiators: dynamic configuration, custom vConsole plugins, multi-page support, and environment-aware enabling/disabling. Compared to alternatives like manually adding vConsole, this plugin automates the setup and teardown process, ensuring vConsole is only loaded when needed (e.g., development or test builds).

Common errors

error Cannot find module 'vconsole' ↓

cause vconsole not installed or installed as devDependency instead of dependency.

fix

npm install vconsole --save

error TypeError: viteVConsole is not a function ↓

cause Default import used instead of named import.

fix

Change to import { viteVConsole } from 'vite-plugin-vconsole'

error Error: ENOENT: no such file or directory, open '.../src/main.ts' ↓

cause Relative path used for entry option.

fix

Use path.resolve() to get absolute path: entry: path.resolve('src/main.ts')

error vConsole is not defined ↓

cause enabled is true but vconsole package missing from production bundle.

fix

Ensure vconsole is in dependencies, not devDependencies.

Warnings

breaking v1.x option 'localEnable' was removed in v2.0.0; use 'enabled' instead. ↓

fix Replace localEnable with enabled. The enabled option now supports boolean or function returning boolean.

breaking v2.0.0 changed the way custom plugins are passed; now uses 'plugin' array with objects containing id, name, event array. ↓

fix Follow new plugin structure: plugin: [{ id: 'myPlugin', name: 'My Plugin', event: [ { eventName: 'init', callback() {} } ] }]

deprecated Options 'vconsole' (lowercase) is deprecated since v2.0.0; use 'viteVConsole' export. ↓

fix Import { viteVConsole } instead of { vconsole }.

gotcha vconsole must be installed as a production dependency (not devDependency) because it is injected into the bundle. ↓

fix Run 'npm install vconsole' without --save-dev (or -S).

gotcha The 'entry' option must be an absolute path or array of absolute paths. Relative paths like 'src/main.ts' will fail silently. ↓

fix Use path.resolve('src/main.ts') or __dirname + '/src/main.ts'.

gotcha If using TypeScript, ensure you import types with 'import type' to avoid runtime errors. ↓

fix Use 'import type { ViteVConsoleOptions } from 'vite-plugin-vconsole'.

Install

npm install vite-plugin-vconsole

yarn add vite-plugin-vconsole

pnpm add vite-plugin-vconsole

Imports

viteVConsole

wrong

import viteVConsole from 'vite-plugin-vconsole'

correct

import { viteVConsole } from 'vite-plugin-vconsole'

Named export, not default. ESM only; no CJS export.

viteVConsole (type)

wrong

import { ViteVConsoleOptions } from 'vite-plugin-vconsole'

correct

import type { ViteVConsoleOptions } from 'vite-plugin-vconsole'

Use type import for TypeScript. Available since v2.0.0.

viteVConsole config object
wrong
```
viteVConsole({ entry: '/src/main.ts', enabled: true })
```
correct
```
viteVConsole({ entry: path.resolve('src/main.ts'), enabled: true, config: { theme: 'dark' } })
```
entry must be an absolute path or array of absolute paths (use path.resolve). enabled controls injection; can be based on mode/command.

Quickstart

Shows basic Vite config with vite-plugin-vconsole for Vue, enabling vConsole in non-production environments.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteVConsole } from 'vite-plugin-vconsole';
import * as path from 'path';

export default defineConfig({
  plugins: [
    vue(),
    viteVConsole({
      entry: path.resolve('src/main.ts'),
      enabled: process.env.NODE_ENV !== 'production',
      config: {
        maxLogNumber: 1000,
        theme: 'dark'
      }
    })
  ]
});