ifdef-loader

2.3.2 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that adds conditional compilation directives (`#if`, `#elif`, `#else`, `#endif`) inside JavaScript or TypeScript comments, processed at build time. Current stable version is 2.3.2 (last released on npm), with no fixed release cadence; the project appears to be in maintenance mode with infrequent updates. Key differentiators: directives are written inside triple-slash comments so they don't interfere with normal parsing or linters; supports nested conditions, arbitrary JS expressions, and an uncomment-prefix feature to hide syntactically invalid code in comments. Comparable to `preprocessor-loader` or manual environment-based code stripping.

Common errors

error Module build failed (from ./node_modules/ifdef-loader/index.js): TypeError: Cannot read properties of undefined (reading 'indexOf') ↓

cause Loader executed on a file without any ifdef comments; the loader is chained incorrectly or file is empty.

fix

Ensure the loader is only applied to files that contain conditional compilation directives, or add a #if at least one block.

error ifdef-loader: unknown option `ifdef-verbose` (maybe a typo or missing prefix) ↓

cause Option name misspelled or missing the 'ifdef-' prefix.

fix

Use exactly 'ifdef-verbose' (with hyphen and prefix).

error Unbalanced #if/#endif blocks ↓

cause A `#if` is opened but not closed, or a `#endif` appears without a matching `#if`.

fix

Ensure every #if has a corresponding #endif, and nested blocks are properly balanced.

Warnings

gotcha Triple-slash comments (`///`) are required by default; double-slash comments (`//`) only work if `ifdef-triple-slash: false` is set. ↓

fix Use triple-slash comments or set `ifdef-triple-slash: false` in options.

gotcha Loader order matters: ifdef-loader must appear after ts-loader (or babel-loader) to run before compilation, but its placement in the `use` array is first-to-last executed (last in array runs first). Place ifdef-loader last in the array so it runs first. ↓

fix Put ifdef-loader as the last entry in the `use` array (e.g., `use: ['ts-loader', 'ifdef-loader']`).

gotcha Boolean values in options are stringified: `{ DEBUG: true }` makes `DEBUG` evaluate to string `'true'`, not boolean `true`. JavaScript expressions like `DEBUG === true` will be false. ↓

fix Use string values: `{ DEBUG: 'true' }` and compare with string: `/// #if DEBUG == 'true'`.

deprecated Options prefixed with `ifdef-` (e.g., `ifdef-verbose`) are prefixed for clarity but could be confused with non-prefixed keys; the prefix is mandatory for these special options. ↓

fix Ensure special options always include the `ifdef-` prefix (e.g., `'ifdef-triple-slash': true`).

breaking Version 2.1.0 changed the default comment style from double-slash (`//`) to triple-slash (`///`). Existing configs that rely on double-slash will stop working. ↓

fix Either update all directives to triple-slash comments or set `ifdef-triple-slash: false` in options.

Install

npm install ifdef-loader

yarn add ifdef-loader

pnpm add ifdef-loader

Imports

ifdef-loader (default import)
wrong
```
const ifdefLoader = require('ifdef-loader');
```
correct
```
import ifdefLoader from 'ifdef-loader';
```
Since ifdef-loader is a Webpack loader, it's typically referenced as 'ifdef-loader' string in webpack config, not imported directly. Direct import is rare and may not be type-safe; use the string reference.

loader options (object literal)

wrong

use: [{ loader: 'ifdef-loader', options: { 'DEBUG': true } }] (keys must be strings, but they can be identifiers)

correct

use: [{ loader: 'ifdef-loader', options: { DEBUG: true, version: 3 } }]

Options are passed as plain object; each key becomes a variable in the preprocessor expressions. Boolean values are cast to string 'true'.

query string parameters
wrong
```
'ifdef-loader?DEBUG=true' (throws because value is not JSON-encoded; use querystring module instead)
```
correct
```
const q = require('querystring').encode({ DEBUG: true }); 'ifdef-loader?' + q
```
When using query string, values must be encoded with Node's querystring module. Simple string values like `true` will be interpreted as string 'true', not boolean.

Quickstart

Demonstrates Webpack config with ifdef-loader placed after ts-loader, enabling DEBUG variable and all supported options.

// webpack.config.js
const path = require('path');
const opts = {
  DEBUG: true,
  version: 3,
  'ifdef-verbose': true,
  'ifdef-triple-slash': false, // use double slash comment
  'ifdef-fill-with-blanks': true,
  'ifdef-uncomment-prefix': '// #code '
};

module.exports = {
  entry: './src/index.ts',
  output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist') },
  resolve: { extensions: ['.ts', '.js'] },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        exclude: /node_modules/,
        use: [
          { loader: 'ts-loader' },
          { loader: 'ifdef-loader', options: opts }
        ]
      }
    ]
  }
};

// src/index.ts
/// #if DEBUG
console.log('Debug mode');
/// #endif