1 | # Babel Debug Macros And Feature Flags
|
2 |
|
3 | This provides debug macros and feature flagging.
|
4 |
|
5 | ## Setup
|
6 |
|
7 | The plugin takes 5 types options: `envFlags`, `features`, `debugTools`, `externalizeHelpers` and `svelte`. 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 you're own helpers using the `externalizeHelpers` options.
|
8 |
|
9 | ```
|
10 | {
|
11 | plugins: [
|
12 | ['babel-debug-macros', {
|
13 | // @required
|
14 | envFlags: {
|
15 | source: '@ember/env-flags',
|
16 | flags: { DEBUG: true }
|
17 | },
|
18 | // @required
|
19 | debugTools: {
|
20 | source: 'debug-tools'
|
21 | },
|
22 | // @optional
|
23 | features: {
|
24 | name: 'ember-source',
|
25 | source: '@ember/features',
|
26 | flags: { FEATURE_A: false, FEATURE_B: true, DEPRECATED_CONTROLLERS: "2.12.0" }
|
27 | },
|
28 | // @optional
|
29 | svelte: {
|
30 | 'ember-source': "2.15.0"
|
31 | },
|
32 | // @optional
|
33 | externalizeHelpers: {
|
34 | module: true,
|
35 | // global: '__my_global_ns__'
|
36 | }
|
37 | }]
|
38 | ]
|
39 | }
|
40 | ```
|
41 |
|
42 | Flags and features are inlined into consuming module so that something like UglifyJS with DCE them when they are unreachable.
|
43 |
|
44 | ## Simple environment and fetaure flags
|
45 |
|
46 | ```javascript
|
47 | import { DEBUG } from '@ember/env-flags';
|
48 | import { FEATURE_A, FEATURE_B } from '@ember/features';
|
49 |
|
50 | if (DEBUG) {
|
51 | console.log('Hello from debug');
|
52 | }
|
53 |
|
54 | let woot;
|
55 | if (FEATURE_A) {
|
56 | woot = () => 'woot';
|
57 | } else if (FEATURE_B) {
|
58 | woot = () => 'toow';
|
59 | }
|
60 |
|
61 | woot();
|
62 | ```
|
63 |
|
64 | Transforms to:
|
65 |
|
66 | ```javascript
|
67 | if (true) {
|
68 | console.log('Hello from debug');
|
69 | }
|
70 |
|
71 | let woot;
|
72 | if (false) {
|
73 | woot = () => 'woot';
|
74 | } else if (true) {
|
75 | woot = () => 'toow';
|
76 | }
|
77 |
|
78 | woot();
|
79 | ```
|
80 |
|
81 | ## `warn` macro expansion
|
82 |
|
83 | ```javascript
|
84 | import { warn } from 'debug-tools';
|
85 |
|
86 | warn('this is a warning');
|
87 | ```
|
88 |
|
89 | Expands into:
|
90 |
|
91 | ```javascript
|
92 | (true && console.warn('this is a warning'));
|
93 | ```
|
94 |
|
95 | ## `assert` macro expansion
|
96 |
|
97 | ```javascript
|
98 | import { assert } from 'debug-tools';
|
99 |
|
100 | assert((() => {
|
101 | return 1 === 1;
|
102 | })(), 'You bad!');
|
103 | ```
|
104 |
|
105 | Expands into:
|
106 |
|
107 | ```javascript
|
108 |
|
109 | (true && console.assert((() => { return 1 === 1;})(), 'this is a warning'));
|
110 | ```
|
111 |
|
112 | ## `deprecate` macro expansion
|
113 |
|
114 | ```javascript
|
115 | import { deprecate } from 'debug-tools';
|
116 |
|
117 | let foo = 2;
|
118 |
|
119 | deprecate('This is deprecated.', foo % 2);
|
120 | ```
|
121 |
|
122 | Expands into:
|
123 |
|
124 | ```javascript
|
125 | let foo = 2;
|
126 |
|
127 | (true && !(foo % 2) && console.warn('This is deprecated.'));
|
128 | ```
|
129 |
|
130 | ## Externalized Helpers
|
131 |
|
132 | When you externalize helpers you must provide runtime implementations for the above macros. An expansion will still occur however we will use emit references to those runtime helpers.
|
133 |
|
134 | A global expansion looks like the following:
|
135 |
|
136 | ```javascript
|
137 | import { warn } from 'debug-tools';
|
138 |
|
139 | warn('this is a warning');
|
140 | ```
|
141 |
|
142 | Expands into:
|
143 |
|
144 | ```javascript
|
145 | (true && Ember.warn('this is a warning'));
|
146 | ```
|
147 |
|
148 | While externalizing the helpers to a module looks like the following:
|
149 |
|
150 | ```javascript
|
151 | import { warn } from 'debug-tools';
|
152 |
|
153 | warn('this is a warning');
|
154 | ```
|
155 |
|
156 | Expands into:
|
157 |
|
158 | ```javascript
|
159 | (true && warn('this is a warning'));
|
160 | ```
|
161 |
|
162 | # Svelte
|
163 |
|
164 | 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.
|
165 |
|
166 | 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.
|
167 |
|
168 | ```
|
169 | ...
|
170 | svelte: {
|
171 | "ember-source": "2.10.0"
|
172 | }
|
173 | ...
|
174 | ```
|
175 |
|
176 | 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.
|
177 |
|
178 | ```
|
179 | svelte: {
|
180 | "ember-source": "2.11.0"
|
181 | }
|
182 | ```
|
183 |
|
184 | # Hygenic
|
185 |
|
186 | As you may notice that we inject `DEBUG` into the code when we expand the macro. We gurantee that the binding is unique when injected and follow the local binding name if it is imported directly.
|