Quickstart

Compatibility

Stack	Versions tested
Vite	6.x · 7.x · 8.x
Node.js	≥ 20.19 (LTS 22 recommended)
Vue	3.5+ (Composition + Options API, Pinia, Vue Router)
React	18+ (Redux Toolkit, React Router)
Angular	20+ via Analog (NgRx, Angular Router)
Nuxt	4.x (Pinia, route middleware)
SSR engines	Vite SSR, Analog, Nitro/Nuxt, vite-node

See Framework recipes for call-site snippets per stack.

Install

npm install -D @mars-tech/vite-debug-plugin

Quickstart (30 seconds)

npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install -D @mars-tech/vite-debug-plugin

Add mtDebug() to the plugins array in vite.config.ts, drop a triple-slash reference into src/vite-env.d.ts, then call $debug('info', 'hello') anywhere in src/. Open the browser DevTools console and the Vite terminal side-by-side to see the same line on both. The steps below detail each part.

Usage

1. Add the plugin

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import mtDebug from "@mars-tech/vite-debug-plugin";

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

The default export is the plugin factory — works identically with import (ESM) and require() (CommonJS). Every setting it accepts is described in Plugin options.

2. Enable the global type

Add a triple-slash reference where your project's ambient types live (commonly src/vite-env.d.ts):

/// <reference types="@mars-tech/vite-debug-plugin/client" />

Module resolution must read the package exports map (moduleResolution: "bundler", "node16", or "nodenext"). On legacy "node10" / "classic", the package also ships a root-level client.d.ts that resolves by path — no change needed.

Tell ESLint about the global

TypeScript now knows $debug, but ESLint's no-undef rule doesn't read TS types — it will report '$debug' is not defined. Spread the shipped flat config to declare the global:

// eslint.config.js (flat config, ESLint 9+)
import mtDebug from "@mars-tech/vite-debug-plugin/eslint";

export default [
  mtDebug, // declares $debug as a readonly global
  // ...your other configs
];

• Custom globalName? Use the factory: import { mtDebugFlatConfig } from "@mars-tech/vite-debug-plugin/eslint" → mtDebugFlatConfig({ globalName: "$log" }).
• Legacy .eslintrc: const { mtDebugGlobals } = require("@mars-tech/vite-debug-plugin/eslint") → { globals: mtDebugGlobals() }.
• TypeScript users can alternatively just disable no-undef for .ts files — tsc already catches undefined names.

3. Call $debug anywhere in dev code

$debug("warning", new Error('Invalid variant "danger"'), {
  tag: "PropsValidator",
});

Output (both browser console and Vite terminal):

MARS-TECH Warning [PropsValidator] - Invalid variant "danger"

MARS-TECH is the default prefix, followed by the level label, the tag and the message. With source locations on (the showSourceLocation default), the line also ends with a (file:line:column) location. In 0.6 that location points inside the plugin's own code, not at your call: in the browser it is the injected runtime (for example /@mars-tech-vite-debug/runtime:201:3), and on the server it is the plugin's SSR runtime or dev-server logger. Version 1.0 fixes this.

Next steps

• The $debug API: call signature, payload rendering and utility helpers.
• Framework recipes: idiomatic call sites in Vue, React, Angular and Nuxt.
• Namespaces and filtering: choose what shows at runtime, without restarting.
• Production behavior: what happens to the calls in vite build.