esbuild-plugin-jscc

1.1.2 verified Fri May 01 auth: no javascript

JSCC plugin for esbuild that enables conditional compilation using JSCC directives (e.g., //#if, //#ifdef, //#endif) in JavaScript and TypeScript bundles. Version 1.1.2, actively maintained. Integrates seamlessly with esbuild's build pipeline, allowing you to include or exclude code blocks at build time based on predefined or environment variables. Useful for toggling debug code, feature flags, or platform-specific snippets without runtime overhead. Unlike alternatives like preprocessor or esbuild-plugin-condition, it leverages JSCC syntax familiar to developers using JSCC with other bundlers.

Common errors

error Error: The plugin "jscc" must be an object with a "name" and "setup" function. ↓

cause Importing the plugin incorrectly (e.g., using named import instead of default).

fix

Use default import: import jscc from 'esbuild-plugin-jscc'

error Error: Cannot find module 'esbuild-plugin-jscc' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install esbuild-plugin-jscc --save-dev

Warnings

gotcha Plugin only processes files processed by esbuild. Files not bundled (e.g., external) will not be transformed. ↓

fix Ensure all entry points are included in the build and not marked as external if you need JSCC processing.

breaking Version 1.0.0 changed the plugin API from a factory function to a default export. ↓

fix Update import from 'const jscc = require("esbuild-plugin-jscc")' to 'import jscc from "esbuild-plugin-jscc"'.

Install

npm install esbuild-plugin-jscc

yarn add esbuild-plugin-jscc

pnpm add esbuild-plugin-jscc

Imports

default
wrong
```
const jscc = require('esbuild-plugin-jscc')
```
correct
```
import jscc from 'esbuild-plugin-jscc'
```
Package exports a single default function. ESM only; CommonJS require is not supported.

jscc

wrong

import { jscc } from 'esbuild-plugin-jscc'

correct

import jscc from 'esbuild-plugin-jscc'

Default export, not named. Do not use destructuring.

JsccOptions
```
import type { JsccOptions } from 'esbuild-plugin-jscc'
```
TypeScript users can import the type for full options. Available in v1.1+.

Quickstart

Sets up esbuild with the JSCC plugin to conditionally include debug code when DEBUG is true.

import esbuild from 'esbuild';
import jscc from 'esbuild-plugin-jscc';

// Example with conditional logs
// In your source code:
// //#if DEBUG
// console.log('Debug mode');
// //#endif

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [jscc({ values: { DEBUG: true } })],
});