vite-plugin-keep-console

vite-plugin-keep-console turns production log cleanup into an explicit build policy. Instead of a one-off "delete every console.log" transform, it lets a Vite project decide which console methods are processed, which files are included, which comments preserve diagnostics, whether the build only reports findings, and whether CI should fail when unapproved console calls remain.

Positioning

This project is best described as a console-policy plugin for Vite.

• Remove mode strips unmarked matching console calls from production bundles.

• Report mode keeps source unchanged but records findings for review or CI.

• Keep mode leaves matching console calls in place while still allowing report aggregation.

• Fail gate turns unmarked console findings into a build error when failOnConsole is enabled.

Core Design

The Vite plugin is small at the entry point and deliberate behind it.

:: ConsoleKeeper() creates a normalized policy, registers a transform hook for build mode, resets an aggregate report on buildStart, and prints or fails from buildEnd.

:: generateTransform() decides whether a file should be transformed, resolves one AST backend lazily, transforms Vue/Svelte <script> blocks without touching templates, and merges backend stats into the build report.

:: Backends share the same policy contract. Babel uses parser/traverse/generator; OXC uses oxc-parser plus magic-string. backend: "auto" prefers OXC only when the Node runtime supports it and falls back to Babel otherwise.

flowchart TD
  Vite["Vite build transform"] --> Match["include / exclude / extension gate"]
  Match --> Blocks["JS/TS/JSX/TSX or Vue/Svelte script blocks"]
  Blocks --> Backend["Babel or OXC AST backend"]
  Backend --> Policy["method filter + keep comments + mode"]
  Policy --> Output["remove / keep / report"]
  Output --> BuildEnd["summary + failOnConsole gate"]

Policy Surface

Legacy aliases are still supported: includes maps to methods, and external maps to include.

Why AST, Not Regex

The plugin needs to understand whether console.warn() is a full statement, part of a ternary, inside a JSX handler, or carrying comments around the call. A regex delete pass cannot make those distinctions safely.

The Babel backend replaces expression-position console calls with undefined, while preserveArguments can rewrite console.log(expensive(), value) into a sequence expression so expensive() still runs. The OXC backend follows the same behavior through range mutations and source-preserving updates.

File-Type Coverage

• .js, .jsx, .ts, and .tsx are parsed as source modules.

• .vue and .svelte raw files are supported by transforming only <script> blocks.

• Templates and markup are left untouched, avoiding false parsing failures in framework-specific syntax.

• File ids are cleaned before matching, so Vite query/hash suffixes do not break include/exclude rules.

What Makes It Useful

1. Teams can keep production diagnostics intentionally instead of relying on broad minifier settings.

2. CI can block accidental debug logs while still allowing marked operational logs.

3. Report-only mode gives maintainers a migration path before enforcing removal.

4. OXC can be adopted opportunistically without making older Node/Vite environments unusable.

Open-Source Signals

• TypeScript public option types with compatibility aliases for older users.

• Dedicated tests for option normalization, backend resolution, file types, policy modes, and transform behavior.

• Package exports aligned to built ESM, CJS, and type declaration outputs.

• README and Chinese README describe the policy model, backend strategy, and comment placement rules.

Best-Fit Use Cases

• Vite applications that want production console control without moving that decision into application code.

• Libraries that want a build-time report of console usage before publishing.

• Teams that distinguish operational diagnostics from accidental debug logging.

• Projects migrating from simple remove-console behavior to auditable build policy.