Plugin options

All settings are passed to the plugin factory in vite.config.ts. The example below lists every option:

import { DEFAULT_COLORS } from "@mars-tech/vite-debug-plugin/helpers";

mtDebug({
  enabled: true,
  levels: ["error", "warning", "info", "debug", "success", "trace"],
  // minLevel: "debug", // ignored when `levels` is also set (see below)
  terminal: true,
  browser: true,
  showSourceLocation: true,
  prefix: "MARS-TECH",
  colors: {
    warning: { ...DEFAULT_COLORS.warning, label: "Warn" },
  },
  globalName: "$debug",
  prefixFilter: "-NoisyLib",
  stripInDeps: ["@your-org/some-pinia-plugin"],
  allowDebugBuild: false,
  libraryPrefix: false,
  redact: [/x-api-key: \S+/, "supersecret"],
  redactDefaults: false,
  testStub: true,
  testLog: false,
});

Option	Type	Default
enabled	boolean	active in vite dev, inert in vite build
levels	MTLevel[]	all levels
minLevel	MTLevel	unset
terminal	boolean	true
browser	boolean	true
showSourceLocation	boolean	true
prefix	string	'MARS-TECH'
colors	Partial<MTColorMap>	unset
globalName	string	'$debug'
prefixFilter	string	unset
stripInDeps	(string | RegExp)[]	[]
allowDebugBuild	boolean	false
libraryPrefix	boolean	false
redact	(string | RegExp)[]	[]
redactDefaults	boolean	false
testStub	boolean	true
testLog	boolean	false

enabled

Master switch. By default the plugin is active when Vite serves the app (vite dev, where the plugin checks command === 'serve') and inert in vite build, whatever --mode is.

Setting false turns the plugin off in vite dev: no runtime is injected and $debug calls are stripped, except with allowDebugBuild: true, where in 0.6 the calls stay in place and throw ReferenceError. Under Vitest, enabled: false does not stop testStub / testLog. true cannot force it on in a build.

Note

The 0.6.1 README gives this default as mode === 'development'. The plugin actually checks the Vite command, so vite build --mode development still strips every call.

levels

Allowlist of the levels to keep.

If both levels and minLevel are set, the plugin prints a warning when the Vite config loads, and a non-empty levels wins: minLevel is ignored. An empty levels array counts as unset.

minLevel

Threshold (trace < debug < info < success < warning < error): keeps the given level and every level above it. Ignored when a non-empty levels is set.

The browser and server can raise this floor at runtime, never lower it below the build-time set: see Namespaces and filtering.

terminal

Print to Vite stdout, the dev-server terminal. When false, lines logged in the browser are no longer forwarded to the terminal.

In 0.6, the runtime auto-injected into server-rendered modules (virtual:mt-debug/ssr, see SSR) writes to process.stdout regardless of this option.

browser

Print to the browser console.

showSourceLocation

Default for the per-call showSource option (see the function signature).

Location points at the plugin in 0.6

In 0.6 the printed (file:line:column) is a frame inside the plugin's own code (in the browser, /@mars-tech-vite-debug/runtime), never your call site, in the browser and on the server. Version 1.0 fixes this.

prefix

Output prefix: the head of every rendered line. A single call can override it with the prefix call option, and a library can keep its own prefix in a consuming app with libraryPrefix.

colors

Per-level color overrides; missing keys fall back to the defaults listed in Levels. Each level entry has three fields: ansi (the function that colors terminal output), css (the browser console color) and label.

In 0.6, lines written by the SSR runtime (virtual:mt-debug/ssr) keep the default terminal colors: only label overrides reach them.

Color override merge

User-supplied colors deep-merges per level:

mtDebug({
  colors: {
    error: { label: "Error123" },
  },
});

Resolves to:

{
  error: { ansi: red, css: '#ef4444', label: 'Error123' },
  // other levels untouched
}

TypeScript in 0.6

In 0.6, the colors type requires all three fields (ansi, css, label) for each level you override. A label-only override merges correctly at runtime but fails type-checking. Spread the default entry to stay type-valid:

import { DEFAULT_COLORS } from "@mars-tech/vite-debug-plugin/helpers";

mtDebug({
  colors: {
    error: { ...DEFAULT_COLORS.error, label: "Error123" },
  },
});

globalName

Identifier attached to globalThis. The production strip removes calls to this identifier (see Production behavior).

Custom globalName

When you change globalName, the shipped client .d.ts no longer matches. Add your own augmentation:

// src/vite-env.d.ts
import type {
  MTLevel,
  MTCallOptions,
} from "@mars-tech/vite-debug-plugin/helpers";

declare global {
  function myDebug<T>(
    level: MTLevel,
    payload: string | Error | T,
    options?: MTCallOptions,
  ): void;
}

export {};

This declaration types the call itself. The shipped /client types declare var $debug: MTDebug; to also type the runtime controls and helpers (ns, enable, time…) under your name, declare var myDebug: MTDebug instead, with MTDebug imported from @mars-tech/vite-debug-plugin/helpers.

A rename also affects the other integrations:

• ESLint: the default flat config declares $debug only. Use the factory instead: mtDebugFlatConfig({ globalName: "myDebug" }) from @mars-tech/vite-debug-plugin/eslint (legacy .eslintrc: { globals: mtDebugGlobals("myDebug") }). See Usage.
• Vitest: the automatic no-op stub only installs $debug. Set testStub: false and call installMtDebugStub({ globalName: "myDebug" }) from a setup file (see Testing). With testLog: true, the auto-registered console logger uses your custom name.

prefixFilter

Build-time default prefix filter: mute or isolate logs by rendered prefix (debug-style syntax). Overridden by ?mt-debug-prefix=, localStorage, MT_DEBUG_PREFIX and $debug.setPrefixFilter(...). See Prefix filtering.

stripInDeps

Opt selected node_modules packages into the production strip transform. Fallback for libraries that don't ship their own dual variant (see Library authoring).

By default the plugin skips every module whose path contains node_modules, so $debug(...) calls baked into a published library survive in the consuming app's build. A string entry matches any module path that contains it (a bare package name works); a RegExp is tested against the module path. The type definitions recommend pairing it with optimizeDeps.exclude for the same packages, so Vite serves them as source modules the strip transform sees reliably.

allowDebugBuild

Library mode: vite build emits a dual output (dist/ stripped, and dist/debug/ with calls preserved plus an auto-prepended fallback shim). See Library authoring with allowDebugBuild.

libraryPrefix

Library mode: stamp this library's prefix onto its $debug calls so they stay branded when consumed, instead of inheriting the app's prefix. Requires allowDebugBuild. See Branding library logs with libraryPrefix.

redact

Mask matches in the rendered message ([redacted]), across browser and terminal. Strings match literally; a RegExp is applied globally and may keep a $1 group. See Redacting secrets.

redactDefaults

Also apply a curated secret set (JWTs, Bearer tokens, emails, Stripe-style keys, secret JSON values). See Redacting secrets.

testStub

Under Vitest, auto-register a first setupFiles entry that installs a no-op $debug (default global only). Set false to manage it yourself. Jest, and Vitest configs that don't include this plugin, add @mars-tech/vite-debug-plugin/testing to setupFiles instead. See Testing.

testLog

Under Vitest, make that auto setup install a real, config-aware console logger instead of the no-op: component and test-file $debug(...) calls print with your configured prefix, globalName and levels. Requires testStub on. In 0.6 this logger does not apply redact / redactDefaults, uses the default level labels and colors, and prints no source location or stack. See Seeing $debug output in tests.