Vite Check Multiple DOM

0.2.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that captures Vue <Transition> runtime warnings about multiple root nodes and displays actionable fix suggestions via Vite's error overlay during development. Current version 0.2.2, updated occasionally. Key differentiators: focuses exclusively on the common Vue Transition multi-root pitfall, provides localized (zh/en) messages, integrates with Vite's HMR WebSocket for seamless overlay display, and supports both plugin (vite.config) and client (main.ts) setup. Requires Vue >=3.0.0 and Vite >=4.0.0.

Common errors

error Cannot find module 'vite-check-multiple-dom/client' or its corresponding type declarations. ↓

cause Missing subpath export in package.json or TypeScript not configured for subpath imports.

fix

Ensure your TypeScript version supports subpath exports (>=4.7) and that your tsconfig.json includes 'moduleResolution': 'node16' or 'bundler'.

error TypeError: vueRootValidator is not a function ↓

cause Importing the plugin incorrectly (named import instead of default).

fix

Use default import: import vueRootValidator from 'vite-check-multiple-dom'

error Vite Error Overlay not showing for Transition warnings ↓

cause Possible missing WebSocket connection or warnHandler not triggered (e.g., production mode).

fix

Run Vite dev server (not production build). Check browser console for Vue warnings; if they appear, ensure the plugin is correctly set up in both vite.config.ts and main.ts.

Warnings

gotcha The plugin only works in Vite dev server, not in production builds. ↓

fix Use only during development; ensure the plugin is not included in production build config.

gotcha setupVueRootValidator must be called before app.mount(). ↓

fix Place setupVueRootValidator call after all other plugin setups but before mount.

gotcha Language configuration in vite.config.ts is not supported; lang only works in client setup. ↓

fix Pass the lang option only to setupVueRootValidator in main.ts.

deprecated Using CommonJS require() may cause issues; package is ESM-only. ↓

fix Use ES module imports. For vite.config.ts, ensure it is an ES module.

gotcha The plugin intercepts all Vue warnings via warnHandler; may conflict with other custom warnHandler setups. ↓

fix If you have your own warnHandler, you may need to combine them manually.

Install

npm install vite-check-multiple-dom

yarn add vite-check-multiple-dom

pnpm add vite-check-multiple-dom

Imports

default (plugin)

wrong

import { vueRootValidator } from 'vite-check-multiple-dom'

correct

import vueRootValidator from 'vite-check-multiple-dom'

Default export is the Vite plugin function.

setupVueRootValidator

wrong

import { setupVueRootValidator } from 'vite-check-multiple-dom'

correct

import { setupVueRootValidator } from 'vite-check-multiple-dom/client'

The client setup must be imported from 'vite-check-multiple-dom/client' subpath.

type imports (TypeScript)
```
import type { SetupOptions } from 'vite-check-multiple-dom/client'
```
Types are exported from the client subpath; no explicit type exports from the main plugin.

Quickstart

Demonstrates plugin registration in vite.config.ts and client-side setup in main.ts.

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vueRootValidator from 'vite-check-multiple-dom';

export default defineConfig({
  plugins: [vue(), vueRootValidator()]
});

// main.ts (or main.js)
import { createApp } from 'vue';
import App from './App.vue';
import { setupVueRootValidator } from 'vite-check-multiple-dom/client';

const app = createApp(App);
setupVueRootValidator(app, { lang: 'zh' });
app.mount('#app');