# babel-plugin-debug-macros

> Debug macros and feature flag stripping

Latest version **2.0.0** (published 2025-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install babel-plugin-debug-macros
pnpm add babel-plugin-debug-macros
yarn add babel-plugin-debug-macros
bun add babel-plugin-debug-macros
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2025-07-29 |
| First published | 2017-03-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=16 |
| Dependencies | 2 |
| Unpacked size | 66.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Maintainers | ef4, rwjblue, chadhietala, katiegengler, turbo87 |
| Keywords | babel, plugin |

## Links

- npm: https://www.npmjs.com/package/babel-plugin-debug-macros
- Repository: https://github.com/ember-cli/babel-plugin-debug-macros
- Homepage: https://github.com/ember-cli/babel-plugin-debug-macros#readme
- Issues: https://github.com/ember-cli/babel-plugin-debug-macros/issues
- npm.io page: https://npm.io/package/babel-plugin-debug-macros

## Dependencies (2)

- [semver](https://npm.io/package/semver.md) ^7.6.0
- [babel-import-util](https://npm.io/package/babel-import-util.md) ^2.0.2

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2025-07-29
- 1.0.0-alpha.2 (alpha) — 2024-04-17
- 0.2.0-beta.6 (next) — 2018-05-24
- 1.0.2 — 2024-07-11
- 1.0.1 — 2024-07-11
- 1.0.0 — 2024-04-27
- 1.0.0-alpha.1 — 2024-04-11
- 1.0.0-alpha.0 — 2024-04-11
- 0.3.4 — 2021-01-27
- 0.3.3 — 2019-08-26
- 0.3.2 — 2019-06-20
- 0.3.1 — 2019-04-11
- 0.3.0 — 2019-01-29
- 0.2.0 — 2018-10-03
- 0.2.0-beta.5 — 2018-05-22
- … 21 more at https://npm.io/package/babel-plugin-debug-macros/versions

## README

# Babel Debug Macros And Feature Flags

This provides debug macros and feature flagging.

## Setup

The plugin takes 4 types options: `flags`, `svelte`, `debugTools`, and
`externalizeHelpers`. The `importSpecifier` is used as a hint to this plugin as
to where macros are being imported and completely configurable by the host.

Like Babel you can supply your own helpers using the `externalizeHelpers`
options.

```js
{
  plugins: [
    ['babel-plugin-debug-macros', {
      // @optional
      debugTools: {
        isDebug: true,
        source: 'debug-tools',
        // @optional
        assertPredicateIndex: 0
      },

      flags: [
        { source: '@ember/env-flags', flags: { DEBUG: true } },
        {
          name: 'ember-source',
          source: '@ember/features',
          flags: {
            FEATURE_A: false,
            FEATURE_B: true,
            DEPRECATED_CONTROLLERS: "2.12.0"
          }
        }
      ],

      // @optional
      svelte: {
        'ember-source': "2.15.0"
      },

      // @optional
      externalizeHelpers: {
        module: true,
        // global: '__my_global_ns__'
      }
    }]
  ]
}
```

Flags and features are inlined into the consuming module so that something like UglifyJS will DCE them when they are unreachable.

## Simple environment and feature flags

```javascript
import { DEBUG } from '@ember/env-flags';
import { FEATURE_A, FEATURE_B } from '@ember/features';

if (DEBUG) {
  console.log('Hello from debug');
}

let woot;
if (FEATURE_A) {
  woot = () => 'woot';
} else if (FEATURE_B) {
  woot = () => 'toow';
}

woot();
```

Transforms to:

```javascript
if (true /* DEBUG */) {
  console.log('Hello from debug');
}

let woot;
if (false /* FEATURE_A */) {
  woot = () => 'woot';
} else if (true) {
  woot = () => 'toow';
}

woot();
```

## `warn` macro expansion

```javascript
import { warn } from 'debug-tools';

warn('this is a warning');
```

Expands into:

```javascript
(true && console.warn('this is a warning'));
```

## `assert` macro expansion

The `assert` macro can expand in a more intelligent way with the correct
configuration. When `babel-plugin-debug-macros` is provided with the
`assertPredicateIndex` the predicate is injected in front of the assertion
in order to avoid costly assertion message generation when not needed.

```javascript
import { assert } from 'debug-tools';

assert((() => {
  return 1 === 1;
})(), 'You bad!');
```

With the `debugTools: { assertPredicateIndex: 0 }` configuration the following expansion is done:

```js
(true && !((() => { return 1 === 1;})()) && console.assert(false, 'this is a warning'));
```

When `assertPredicateIndex` is not specified, the following expansion is done:

```javascript
(true && console.assert((() => { return 1 === 1;})(), 'this is a warning'));
```

## `deprecate` macro expansion

```javascript
import { deprecate } from 'debug-tools';

let foo = 2;

deprecate('This is deprecated.', foo % 2);
```

Expands into:

```javascript
let foo = 2;

(true && !(foo % 2) && console.warn('This is deprecated.'));
```

## Externalized Helpers

When you externalize helpers you must provide runtime implementations for the
above macros. An expansion will still occur, however we will emit references to
those runtime helpers.

A global expansion looks like the following:

```javascript
import { warn } from 'debug-tools';

warn('this is a warning');
```

Expands into:

```javascript
(true && Ember.warn('this is a warning'));
```

While externalizing the helpers to a module looks like the following:

```javascript
import { warn } from 'debug-tools';

warn('this is a warning');
```

Expands into:

```javascript
(true && warn('this is a warning'));
```

# Svelte

Svelte allows for consumers to opt into stripping deprecated code from your
dependecies. By adding a package name and minimum version that contains no
deprecations, that code will be compiled away.

For example, consider you are on `ember-source@2.10.0` and you have no
deprecations. All deprecated code in `ember-source` that is `<=2.10.0` will be
removed.

```

svelte: {
  "ember-source": "2.10.0"
}

```

Now if you bump to `ember-source@2.11.0` you may encounter new deprecations.
The workflow would then be to clear out all deprecations and then bump the
version in the `svelte` options.

```
svelte: {
  "ember-source": "2.11.0"
}
```

---
_Source: https://npm.io/package/babel-plugin-debug-macros · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._