# broccoli-debug

> Enable easy debugging of broccoli pipelines with broccoli-debug!

Latest version **0.6.5** (published 2018-10-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install broccoli-debug
pnpm add broccoli-debug
yarn add broccoli-debug
bun add broccoli-debug
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.5 |
| Published | 2018-10-04 |
| First published | 2014-04-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 9.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Robert Jackson |
| Maintainers | joliss, rwjblue, stefanpenner |
| Keywords | broccoli, plugin |

## Links

- npm: https://www.npmjs.com/package/broccoli-debug
- Repository: https://github.com/broccolijs/broccoli-debug
- Homepage: https://github.com/broccolijs/broccoli-debug#readme
- Issues: https://github.com/broccolijs/broccoli-debug/issues
- npm.io page: https://npm.io/package/broccoli-debug

## Dependencies (6)

- [tree-sync](https://npm.io/package/tree-sync.md) ^1.2.2
- [heimdalljs](https://npm.io/package/heimdalljs.md) ^0.2.1
- [fs-tree-diff](https://npm.io/package/fs-tree-diff.md) ^0.5.2
- [broccoli-plugin](https://npm.io/package/broccoli-plugin.md) ^1.2.1
- [symlink-or-copy](https://npm.io/package/symlink-or-copy.md) ^1.1.8
- [heimdalljs-logger](https://npm.io/package/heimdalljs-logger.md) ^0.1.7

## Recent versions

- 0.6.5 (latest) — 2018-10-04
- 0.6.4 — 2017-11-10
- 0.6.3 — 2017-07-20
- 0.6.2 — 2017-05-26
- 0.6.1 — 2017-05-07
- 0.6.0 — 2017-05-07
- 0.1.1 — 2014-04-24
- 0.1.0 — 2014-04-22

## README

# broccoli-debug [![Build Status](https://travis-ci.org/broccolijs/broccoli-debug.svg?branch=master)](https://travis-ci.org/broccolijs/broccoli-debug) [![Build status](https://ci.appveyor.com/api/projects/status/u6tkot7ru19wntxr/branch/master?svg=true)](https://ci.appveyor.com/project/embercli/broccoli-debug/branch/master)


Utility for build pipeline authors to allow trivial debugging of the Broccoli
pipelines they author.

Heavily inspired by [@stefanpenner](https://github.com/stefanpenner)'s
[broccoli-stew's `debug`](https://github.com/stefanpenner/broccoli-stew/blob/v1.4.2/lib/debug.js)'s helper,
but improved in a few ways:

* Supports leaving debug trees in the build with minimal cost when not being used.
* Supports binary files (e.g. does not write `.png`'s as `utf8` text).
* Adds [debug](https://github.com/visionmedia/debug) style debug matching.

## Usage

### Pipeline Authors

To allow consumers to debug the internals of various stages in your build pipeline,
you create a new instance of `BroccoliDebug` and return it instead.

Something like this:

```js
var BroccoliDebug = require('broccoli-debug');

let tree = new BroccoliDebug(input, `ember-engines:${this.name}:addon-input`);
```

Obviously, this would get quite verbose to do many times, so we have created a shortcut
to easily create a number of debug trees with a shared prefix:

```js
let debugTree = BroccoliDebug.buildDebugCallback(`ember-engines:${this.name}`);

let tree1 = debugTree(input1, 'addon-input');
// tree1.debugLabel => 'ember-engines:<some-name>:addon-input'

let tree2 = debugTree(input2, 'addon-output');
// tree2.debugLabel => 'ember-engines:<some-name>:addon-output
```

### Consumers

Folks wanting to inspect the state of the build pipeline at that stage, would do the following:

```js
BROCCOLI_DEBUG=ember-engines:* ember b
```

Now you can take a look at the state of that input tree by:

```js
ls DEBUG/ember-engines/*
```

### API

```ts
interface BroccoliDebugOptions {
  /**
    The label to use for the debug folder. By default, will be placed in `DEBUG/*`.
  */
  label: string

  /**
    The base directory to place the input node contents when debugging is enabled.

    Chooses the default in this order:

    * `process.env.BROCCOLI_DEBUG_PATH`
    * `path.join(process.cwd(), 'DEBUG')`
  */
  baseDir: string

  /**
    Should the tree be "always on" for debugging? This is akin to `debugger`, its very
    useful while actively working on a build pipeline, but is likely something you would
    remove before publishing.
  */
  force?: boolean
}

class BroccoliDebug {
  /**
    Builds a callback function for easily generating `BroccoliDebug` instances
    with a shared prefix.
  */
  static buildDebugCallback(prefix: string): (node: any, labelOrOptions: string | BroccoliDebugOptions) => BroccoliNode
  constructor(node: BroccoliNode, labelOrOptions: string | BroccoliDebugOptions);
  debugLabel: string;
}
```

## Development

### Installation

* `git clone git@github.com:broccolijs/broccoli-debug.git`
* `cd broccoli-debug`
* `yarn`

### Testing

* `yarn test`

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