esbuild-plugin-conditional-build

1.0.2 verified Fri May 01 auth: no javascript

An esbuild plugin for conditional compilation using `//#if`, `//#else`, and `//#endif` directives in JavaScript/TypeScript files. Version 1.0.2, released as first stable. Requires esbuild and ESM setup (`type: module` in package.json and `.mjs` extensions). Differentiates from other conditional build tools by being lightweight and esbuild-native, using simple comment-based directives.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Package is ESM-only but project is not configured for ESM.

fix

Add "type": "module" to package.json and use .mjs extension for your build script.

error Error: [esbuild] error: No matching files found: /path/to/file.js ↓

cause File does not start with //#conditional comment.

fix

Add //#conditional as first line of the file.

Warnings

breaking Requires ESM: 'type': 'module' in package.json and .mjs file extensions. ↓

fix Add "type": "module" to package.json and rename files to .mjs.

gotcha Files must start with '//#conditional' comment for directives to work. ↓

fix Add //#conditional as the first line of your source files.

gotcha Directives only work in files that are processed by esbuild with this plugin. Not a general preprocessor. ↓

fix Ensure all files with conditional comments are included in esbuild build.

Install

npm install esbuild-plugin-conditional-build

yarn add esbuild-plugin-conditional-build

pnpm add esbuild-plugin-conditional-build

Imports

default

wrong

const conditionalBuild = require('esbuild-plugin-conditional-build')

correct

import conditionalBuild from 'esbuild-plugin-conditional-build'

Package is ESM-only (type: module required). CommonJS require will fail.

conditionalBuild

wrong

import { conditionalBuild } from 'esbuild-plugin-conditional-build'

correct

import conditionalBuild from 'esbuild-plugin-conditional-build'

Exported as default, not named.

types

import type { ConditionalBuildOptions } from 'esbuild-plugin-conditional-build'

Type exports may not exist; always check documentation.

Quickstart

Sets up esbuild with conditional build plugin, defining 'DEVELOPMENT' constant and building entry point.

// build.mjs
import conditionalBuild from 'esbuild-plugin-conditional-build';
import { build } from 'esbuild';

build({
  entryPoints: ['src/foo.js'],
  outdir: 'dist',
  plugins: [
    conditionalBuild(['DEVELOPMENT'])
  ]
}).catch(() => process.exit(1));