Registry / web-framework / esbuild-plugin-ifdef

esbuild-plugin-ifdef

library1.0.1jsnpmunverified

esbuild plugin for conditional compilation using `//#ifdef` comments in JavaScript and TypeScript files. Version 1.0.1 is the latest stable release. It allows developers to include or exclude code blocks based on environment variables before esbuild's tree-shaking phase. Unlike traditional `if (true)` patterns that break function scoping, this plugin removes dead code at the comment level, preserving correct scoping. It filters `process.env` prefixes automatically and supports negation with `!`. The plugin excludes `node_modules` by default for performance and security. Alternative to `esbuild-plugin-conditional` or manual define-based checks, but with a simpler preprocessor-style comment syntax.

web-framework

npm install esbuild-plugin-ifdef

package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-IFD

esbuild-plugin-ifdef

web-frameworkjavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ifdef

✓ import { ifdef } from 'esbuild-plugin-ifdef'

✗ const ifdef = require('esbuild-plugin-ifdef')

The package is ESM-only. If using CommonJS, use dynamic import() or the esm wrapper.

default import

✓ import ifdef from 'esbuild-plugin-ifdef'

✗ import { ifdef } from 'esbuild-plugin-ifdef'

The package exports a default function. Named export also exists as 'ifdef' but the default is the same function. Use either.

TypeScript types

✓ import type { IfdefOptions } from 'esbuild-plugin-ifdef'

✗ import { IfdefOptions } from 'esbuild-plugin-ifdef'

Types are exported, but not used at runtime. Use type import to avoid bundling.

Shows how to use esbuild-plugin-ifdef with esbuild to conditionally include code based on environment variables.

import { build } from 'esbuild'; import ifdef from 'esbuild-plugin-ifdef'; const define = { 'process.env.FEATURE_X': true, 'process.env.FEATURE_Y': false, }; await build({ entryPoints: ['src/index.js'], outfile: 'dist/bundle.js', bundle: true, plugins: [ifdef(define)], });

Debug

Known issues

gotchaThe plugin strips code before esbuild parsing, so you cannot use `//#ifdef` inside already conditionally included code (e.g., inside an `if` block that might be removed). The comment must be in the original source and not in a branch that is fully removed.

fix

Ensure `//#ifdef` comments are in top-level or unreachable code only. Do not nest them inside JavaScript conditional statements that esbuild might evaluate.

affects: >=1.0.0

gotchaThe plugin automatically strips 'process.env.' from keys, but if your define object uses a different prefix (e.g., just 'FEATURE_X'), you must match that key in your comment exactly.

fix

Use the same keys as your `define` object but without 'process.env.' prefix. For example, if define = { 'process.env.FOO': true }, use `//#ifdef FOO`.

affects: >=1.0.0

gotchaNegation syntax uses `!` before the condition: `//#ifdef !CONDITION`. It does NOT support `#ifndef`.

fix

Use `//#ifdef !MY_FLAG` instead of `#ifndef MY_FLAG`.

affects: >=1.0.0

gotchaThe plugin filters files using a base directory and exclude list. If your entry points are outside the base directory, the plugin may skip them silently.

fix

Set `baseDir` to the directory containing your entry points or adjust `exclude` to include the necessary paths.

affects: >=1.0.0

gotchaThe plugin runs on node_modules by default unless you pass an exclude list. The default exclude list includes node_modules, but if you override it, node_modules may be processed, causing slow builds or unexpected behavior.

fix

Always include 'node_modules' in your exclude list if using custom exclude array.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: ifdef is not a function

CommonJS require does not work with ESM-only package.

fix

Use dynamic import: `const ifdef = (await import('esbuild-plugin-ifdef')).default;` or switch to ESM `import`.

Error: No matching define for ifdef condition 'MY_FLAG'

The condition 'MY_FLAG' does not exist in the define object.

fix

Add `'process.env.MY_FLAG': true` to the define object or use a key that exists.

Error: Plugin ifdef: baseDir '/wrong/path' does not exist

The baseDir option points to a non-existent directory.

fix

Set baseDir to an existing directory, e.g., process.cwd() or the project root.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/esbuild-plugin-ifdef ↗