{"id":25350,"library":"esbuild-plugin-ifdef","title":"esbuild-plugin-ifdef","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"git@github.com:Jarred-Sumner/esbuild-plugin-ifdef","tags":["javascript"],"install":[{"cmd":"npm install esbuild-plugin-ifdef","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-ifdef","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-ifdef","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only. If using CommonJS, use dynamic import() or the esm wrapper.","wrong":"const ifdef = require('esbuild-plugin-ifdef')","symbol":"ifdef","correct":"import { ifdef } from 'esbuild-plugin-ifdef'"},{"note":"The package exports a default function. Named export also exists as 'ifdef' but the default is the same function. Use either.","wrong":"import { ifdef } from 'esbuild-plugin-ifdef'","symbol":"default import","correct":"import ifdef from 'esbuild-plugin-ifdef'"},{"note":"Types are exported, but not used at runtime. Use type import to avoid bundling.","wrong":"import { IfdefOptions } from 'esbuild-plugin-ifdef'","symbol":"TypeScript types","correct":"import type { IfdefOptions } from 'esbuild-plugin-ifdef'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport ifdef from 'esbuild-plugin-ifdef';\n\nconst define = {\n  'process.env.FEATURE_X': true,\n  'process.env.FEATURE_Y': false,\n};\n\nawait build({\n  entryPoints: ['src/index.js'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [ifdef(define)],\n});","lang":"typescript","description":"Shows how to use esbuild-plugin-ifdef with esbuild to conditionally include code based on environment variables."},"warnings":[{"fix":"Ensure `//#ifdef` comments are in top-level or unreachable code only. Do not nest them inside JavaScript conditional statements that esbuild might evaluate.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `//#ifdef !MY_FLAG` instead of `#ifndef MY_FLAG`.","message":"Negation syntax uses `!` before the condition: `//#ifdef !CONDITION`. It does NOT support `#ifndef`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `baseDir` to the directory containing your entry points or adjust `exclude` to include the necessary paths.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always include 'node_modules' in your exclude list if using custom exclude array.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use dynamic import: `const ifdef = (await import('esbuild-plugin-ifdef')).default;` or switch to ESM `import`.","cause":"CommonJS require does not work with ESM-only package.","error":"TypeError: ifdef is not a function"},{"fix":"Add `'process.env.MY_FLAG': true` to the define object or use a key that exists.","cause":"The condition 'MY_FLAG' does not exist in the define object.","error":"Error: No matching define for ifdef condition 'MY_FLAG'"},{"fix":"Set baseDir to an existing directory, e.g., process.cwd() or the project root.","cause":"The baseDir option points to a non-existent directory.","error":"Error: Plugin ifdef: baseDir '/wrong/path' does not exist"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}