TSIfDef 1.1.9

English | 简体中文

TSIfDef adds reliable #if conditional compilation to TypeScript. Build multiple products from one source tree while the compiler, editor, and ESLint always see the same active code.

#if BROWSER
export const runtime = "browser";
#elif NODE
export const runtime = "node";
#else
#error Select a supported runtime
#endif

Two Parts

TSIfDef ships as two pieces, and which ones you need depends on how you work:

Part	Required	Install
npm package tsifdef	Always. It is the compiler, the CLI, and the ESLint integration.	npm install -D tsifdef
VSCode extension TSIfDef	Whenever you edit in an IDE. Without it the editor reports #if as errors, since it knows nothing about Profiles.	Search TSIfDef in the Extensions view, or install the VSIX

The extension does not replace the package: the build always comes from the npm package, and the extension makes the editor agree with it.

Quick Start

Install TSIfDef as a development dependency:

npm install -D tsifdef

Create a Profile containing the macros enabled for this build:

["BROWSER"]

Point package.json at that Profile and use TSIfDef as the compiler entry:

{
  "tsifdef": "./Profiles/browser.json",
  "scripts": {
    "build": "tsifdef build",
    "watch": "tsifdef build --watch"
  }
}

Write conditional TypeScript directly in the original source file, as shown in the example above.

Run the normal project build:

npm run build

Only the active branch reaches TypeScript. Source paths, diagnostics, declarations, and source maps still point to the original files.

Product Highlights

• One source tree — no generated shadow project and no duplicated platform code.
• One Profile — builds, editor intelligence, and ESLint use the same macro set.
• Native TypeScript output — original paths and source-map locations are preserved.
• Complete editor feedback — inactive code is dimmed and folded without false errors.
• Production workflows — incremental compilation, watch mode, ESLint, and CI are supported.

Editor Support

The extension dims and folds inactive code, shows the active Profile in the status bar, and keeps the TypeScript language service on the same active source the build uses. Requires VS Code 1.85 or newer.

From the Marketplace — open the Extensions view (Ctrl+Shift+X, or Cmd+Shift+X on macOS), search for TSIfDef, and click Install on the entry published by Tencent TiMi Studio Group. Equivalently, from a terminal:

code --install-extension timi-studio.tsifdef

From a VSIX — for editors that do not reach the VS Code Marketplace, such as CodeBuddy, download tsifdef-<version>.vsix from the latest release and either run

code --install-extension tsifdef-<version>.vsix

or, in the Extensions view, use ⋯ → Install from VSIX.

Then open a project whose package.json contains the tsifdef Profile pointer. One more setting is needed for inactive code to stop erroring, because the bundled tsserver plugin loads through the workspace TypeScript version — see Editor setup.

ESLint

The same tsifdef package includes the ESLint processor and parser wrapper; no second TSIfDef package is required. Add its recommended config to an existing TypeScript flat config:

import tsifdef from "tsifdef/eslint-plugin";

export default [
  // Your existing TypeScript ESLint config,
  tsifdef.configs["flat/recommended"],
];

ESLint then reports against the active source at the original line and column positions, with autofix and quick fixes intact. No rules need to be disabled — formatting rules such as prettier/prettier stay enabled and report only on active code. Legacy .eslintrc setup is documented in the Integration Guide.

Build Behavior

Incremental builds and --watch are supported, and current-project files, include, and exclude settings are honored. Changing the selected Profile forces a full rebuild. outFile and project references (tsc -b) are not supported.

Use tsifdef build --emit-projection <dir> when you need to inspect the exact source view passed to TypeScript.

Documentation

Document	Purpose
Integration Guide	Build, editor, and ESLint setup
Portable Specification	Syntax, behavior, schemas, and conformance fixtures
Changelog	Release history
Contributing	Development and pull-request workflow
Security Policy	Private vulnerability reporting

Requirements

• Node.js 18.17 or newer
• TypeScript 5.5
• VS Code 1.85 or a compatible editor for the VSIX

Development

npm ci
npm test
npm run build

Maintainers can build and verify the npm and VSIX artifacts with npm run release. See CONTRIBUTING.md for the repository workflow.

License

TSIfDef is released under the Apache License 2.0.