vite-plugin-conditional-compile

1.4.5 verified Mon Apr 27 auth: no javascript

A Vite plugin that implements conditional compilation using preprocessor-like directives (#if, #elif, #else, #endif), similar to C/C++ #ifdef. It allows selective inclusion/exclusion of code blocks based on environment variables, custom variables, and logical expressions. Current stable version is 1.4.5, released on an irregular cadence. Key differentiators: supports JSX, Vue templates, and arbitrary file types; integrates with Vite's loadEnv; enables flexible condition syntax with logical operators and nested expressions. Requires Vite ^4.5.0 as a peer dependency. Ships TypeScript types.

Common errors

error SyntaxError: Unexpected token '#' while parsing JSX ↓

cause The plugin is placed after JSX transformer (e.g., @vitejs/plugin-react) and cannot parse the # syntax before JSX is transformed.

fix

Move vitePluginConditionalCompile to the first position in the plugins array.

error Cannot find module '...' or its corresponding type declarations. ↓

cause Using CommonJS require() instead of ESM import – the package exports a default export, not a CommonJS module.exports.

fix

Use import vitePluginConditionalCompile from 'vite-plugin-conditional-compile'.

error TypeError: vitePluginConditionalCompile is not a function ↓

cause Using named import { vitePluginConditionalCompile } instead of default import.

fix

Use import vitePluginConditionalCompile from 'vite-plugin-conditional-compile'.

error ENOENT: no such file or directory, open '.../node_modules/vite-plugin-conditional-compile/package.json' ↓

cause The package was not installed because Vite peer dependency was missing or version mismatch.

fix

Run 'npm install vite@^4.5.0' and then 'npm install vite-plugin-conditional-compile'.

error Unset env variable: DEV is not defined ↓

cause The condition references an env variable that is not set in either plugin env or Vite's loadEnv.

fix

Define the variable in the plugin's env option or ensure it is present in Vite's environment variables.

Warnings

breaking The transform function, previously synchronous, is now async for source map support. ↓

fix If you were relying on synchronous behavior, update your checks to handle async. No code changes needed unless you are extending the plugin.

gotcha Plugin must be placed before other plugins (especially JSX compilers) in the plugins array, otherwise conditions may not be parsed. ↓

fix Ensure vitePluginConditionalCompile is the first plugin in the array.

gotcha Condition expressions must be enclosed in square brackets [] and cannot use angle brackets or other delimiters. ↓

fix Always wrap conditions in [] (e.g., #if [DEV] not #if DEV).

deprecated The 1.3.x version had a different API but is still referenced in README. The current 1.4.x API uses env and include/exclude options. ↓

fix Upgrade to 1.4.5 and use the new configuration format as shown in the README.

gotcha The plugin does not support nested #if directives inside other #if blocks; only one level of condition is allowed. ↓

fix Flatten your conditions or use logical operators (e.g., #if [A && B]).

Install

npm install vite-plugin-conditional-compile

yarn add vite-plugin-conditional-compile

pnpm add vite-plugin-conditional-compile

Imports

default

wrong

const vitePluginConditionalCompile = require('vite-plugin-conditional-compile')

correct

import vitePluginConditionalCompile from 'vite-plugin-conditional-compile'

ESM default export. CommonJS require also works, but the default export is preferred in ESM contexts.

vitePluginConditionalCompile

wrong

import { vitePluginConditionalCompile } from 'vite-plugin-conditional-compile'

correct

import vitePluginConditionalCompile from 'vite-plugin-conditional-compile'

Not a named export; this is the default export with that name.

ViteConditionalCompileOptions
```
import type { ViteConditionalCompileOptions } from 'vite-plugin-conditional-compile'
```
TypeScript type export for the plugin options. Use with 'import type' for correct TypeScript usage.

Quickstart

Configures vite-plugin-conditional-compile with custom env variables and shows how to use directives in JSX.

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginConditionalCompile from 'vite-plugin-conditional-compile';

export default defineConfig({
  plugins: [
    vitePluginConditionalCompile({
      env: {
        DEBUG: true,
        FEATURE_A: 'enabled'
      }
    })
  ]
});

// src/main.jsx
// #if [DEBUG]
console.log('Debug mode');
// #endif

// #if [FEATURE_A=enabled]
console.log('Feature A is enabled');
// #endif