vite-plugin-conditional-compiler

0.4.0 verified Mon Apr 27 auth: no javascript

A Vite plugin for conditional compilation using comments based on environment variables. Current stable version is 0.4.0. It allows developers to include or exclude code blocks at build time by wrapping them in `#v-ifdef`, `#v-elif`, `#v-else`, and `#v-endif` directives that reference Vite environment variables (e.g., `PROD`, `DEV`, custom env vars). Supports logical OR, custom values, and `!=` comparisons. Since v0.2.0, it wraps `unplugin-preprocessor-directives`. Release cadence is moderate with occasional bug fixes and feature releases. Key differentiator: lightweight, no runtime overhead, and works in any file type (JS, CSS, HTML) via comments.

Common errors

error SyntaxError: Unexpected token '!' ↓

cause Using `#v-ifndef` directive which is deprecated and may cause parsing issues in some versions.

fix

Use #v-ifdef !ENV instead of #v-ifndef ENV.

error Cannot find module 'vite-plugin-conditional-compiler' ↓

cause Package not installed or import path incorrect.

fix

Run npm install -D vite-plugin-conditional-compiler and use correct import (default import).

error The plugin does not seem to be working; no compilation happens. ↓

cause Directive syntax or environment variable name is incorrect.

fix

Ensure directives are exactly #v-ifdef, #v-elif, #v-else, #v-endif and environment variables match Vite's (e.g., PROD, DEV, VITE_*).

Warnings

breaking From v0.2.0, the plugin wraps unplugin-preprocessor-directives; the internal implementation changed significantly. ↓

fix Update to v0.2.0 or later; no changes required in usage syntax.

deprecated The `#v-ifndef` directive is deprecated since v0.2.0. Use `#v-ifdef !ENV` instead. ↓

fix Replace `#v-ifndef ENV` with `#v-ifdef !ENV`.

gotcha Only logical OR (`||`) is supported; logical AND (`&&`) is not supported and may cause unexpected behavior. ↓

fix Use multiple `#v-ifdef` blocks or restructure conditionally compiled code to avoid AND logic.

gotcha The plugin processes all files by default (`include: ['**/*']`). Large projects may experience slower build times if no exclude patterns are set. ↓

fix Explicitly set `include` and `exclude` options in plugin configuration to limit processing to relevant files.

breaking In v0.1.0, support for `!=` was added. Previously, only equality checks (implicitly) were possible. ↓

fix Upgrade to v0.1.0+ if you need `!=` comparisons.

gotcha The environment variable must be a Vite environment variable (e.g., `PROD`, `VITE_*`). Variables not exposed by Vite may not work. ↓

fix Ensure the variable is defined in Vite's `define` or `envPrefix` (default `VITE_`).

Install

npm install vite-plugin-conditional-compiler

yarn add vite-plugin-conditional-compiler

pnpm add vite-plugin-conditional-compiler

Imports

default

wrong

import { ConditionalCompile } from 'vite-plugin-conditional-compiler'

correct

import ConditionalCompile from 'vite-plugin-conditional-compiler'

Default import is required; named export is not available.

ConditionalCompile
```
const ConditionalCompile = require('vite-plugin-conditional-compiler')
```
CommonJS require works as the package provides a default export.

Options

import type { Options } from 'vite-plugin-conditional-compiler'

Type-only import for TypeScript users.

Quickstart

Setup the plugin in vite.config.ts and use conditional compilation directives in source files.

// vite.config.ts
import { defineConfig } from 'vite';
import ConditionalCompile from 'vite-plugin-conditional-compiler';

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

// In your source file (e.g., main.ts):
// #v-ifdef VITE_MY_ENV
const myValue = 'This will only compile if VITE_MY_ENV is set and truthy';
// #v-endif

// With negation:
// #v-ifdef !VITE_DEBUG
console.log('This will compile when VITE_DEBUG is not set or falsy');
// #v-endif

// Using custom values with !=:
// #v-ifdef VITE_MODE!='development'
console.log('Not in development mode');
// #v-endif