Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add debug tooling babel plugins. #133

Merged
merged 1 commit into from
Apr 28, 2017
Merged

Conversation

rwjblue
Copy link
Member

@rwjblue rwjblue commented Apr 22, 2017

Implements ember-cli/rfcs#50 and the @ember/debug portion of emberjs/rfcs#176.

Below is the documentation being added to the README explaining the feature.


Debug Tooling

In order to allow addons to easily provide good development mode ergonomics (assertions, deprecations, etc) but still perform well in production mode ember-cli-babel automatically manages stripping / removing certain debug statements. This concept was originally proposed in ember-cli/rfcs#50, but has been slightly modified during implementation (after researching what works well and what does not).

Debug Macros

To add convienient deprecations and assertions, consumers (apps and/or addons) can do the following:

import { deprecate, assert } from '@ember/debug';

export default Ember.Component.extend({
  init() {
    this._super(...arguments);
    deprecate(
      'Passing a string value or the `sauce` parameter is deprecated, please pass an instance of Sauce instead',
      false,
      { until: '1.0.0', id: 'some-addon-sauce' }
    );
    assert('You must provide sauce for x-awesome.', this.sauce);
  }
})

In testing and development environments those statements will be executed (and assert or deprecate as appropriate), but
in production builds they will be inert (and stripped during minification).

General Purpose Env Flags

In some cases you may have the need to do things in debug builds that isn't related to asserts/deprecations/etc. For
example, you may expose certain API's for debugging only. You can do that via the DEBUG environment flag:

import { DEBUG } from '@glimmer/env';

const Component = Ember.Component.extend();

if (DEBUG) {
  Component.reopen({
    specialMethodForDebugging() {
      // do things ;)
    }
  });
}

In testing and development environments DEBUG will be replaced by the boolean literal true, and in production builds it will be replaced by false. When ran through a minifier (with dead code elimination) the entire section will be stripped.

Disabling Debug Tooling Support

If for some reason you need to disable this debug tooling, you can opt-out via configuration.

In an app that would look like:

// ember-cli-build.js
module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-babel': {
      disableDebugTooling: true
    }
  });

  return app.toTree();
}

In an addon that would look like:

// index.js

// ...snip...
init() {
  this._super.init.apply(this, arguments);

  this.options['ember-cli-babel'] = this.options['ember-cli-babel'] || {};
  this.options['ember-cli-babel'].disableDebugTooling = true;
}
// ...snip...

Copy link
Contributor

@cibernox cibernox left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Copy link
Member

@stefanpenner stefanpenner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks awesome (but i did leave some nit-picks)

README.md Outdated
@@ -95,6 +95,92 @@ treeForAddon(tree) {
}
```

### Debug Tooling

In order to allow addons to easily provide good development mode ergonomics (assertions, deprecations, etc) but
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addons and apps?

README.md Outdated

// ...snip...
init() {
this._super.init.apply(this, arguments);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth documenting how an addon would do this? This seems quite off the beaten path

@rwjblue
Copy link
Member Author

rwjblue commented Apr 27, 2017

Pushed an update for the two README tweaks that @stefanpenner mentioned...


#### Debug Macros

To add convienient deprecations and assertions, consumers (in either an app or an addon) can do the following:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you add a bulleted list of available macros, or a link to where they are documented?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, updated!

@stefanpenner
Copy link
Member

:shipit:

@rwjblue rwjblue merged commit cf36136 into emberjs:master Apr 28, 2017
@rwjblue rwjblue deleted the add-stripping branch April 28, 2017 13:52
siva-sundar pushed a commit to siva-sundar/ember-cli-babel that referenced this pull request Feb 11, 2021
Ensure logging filter for parallel stuff follows the existing convent…
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants