Skip to content

Commit a0858fc

Browse files
committed
copy optional features section to 3.4
1 parent b5eb5e5 commit a0858fc

File tree

2 files changed

+79
-0
lines changed

2 files changed

+79
-0
lines changed
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
Because major releases of Ember are not supposed to make breaking changes without prior deprecation, the project has been extremely conservative about changing behaviors that don't have a clear deprecation path. As a result, we've had several quirks of the framework linger into the 3.x series.
2+
3+
To give the project a path forward when a breaking change is mandatory, we've released the [`@ember/optional-features`](https://github.com/emberjs/ember-optional-features) addon.
4+
5+
This addon does nothing by default, but provides a command-line interface to enable and disable breaking changes in Ember.
6+
7+
## Installation
8+
9+
To get started with optional features, you must install the addon:
10+
11+
```bash
12+
ember install @ember/optional-features
13+
```
14+
15+
This will make three new commands available to Ember CLI within your project, `feature:list`, `feature:enable`, and `feature:disable`.
16+
17+
## Listing features
18+
19+
The optional features available to your project will depend on the Ember version your project is using.
20+
21+
To see which optional features are available, you can run the following command:
22+
23+
```bash
24+
$ ember feature:list
25+
Usage:
26+
27+
To list all available features, run ember feature:list.
28+
To enable a feature, run ember feature:enable some-feature.
29+
To disable a feature, run ember feature:disable some-feature.
30+
31+
Available features:
32+
33+
application-template-wrapper (Default: true)
34+
Wrap the top-level application template (application.hbs) with a `<div class="ember-view">` element.
35+
More information: https://github.com/emberjs/rfcs/pull/280
36+
37+
jquery-integration (Default: true)
38+
Adds jQuery to the Ember application.
39+
More information: https://github.com/emberjs/rfcs/pull/294
40+
41+
```
42+
43+
## Enabling or disabling a feature
44+
45+
Once you see a feature that you would like to toggle for your project you can run one of two commands, `ember feature:enable <feature>` and `ember feature:disable <feature>`.
46+
47+
Let us disable `template-only-glimmer-components` to see what happens:
48+
49+
```bash
50+
$ ember feature:disable template-only-glimmer-components
51+
Disabled template-only-glimmer-components. Be sure to commit config/optional-features.json to source control!
52+
```
53+
54+
As we can see from the warning, `@ember/optional-features` has created a file in `config/optional-features.json` to store the configuration for your project.
55+
We commit it to our repository and we are off to the races!
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Ember relied on jQuery in the past, and it still ships with it by default.
2+
However, in Ember 3.3 it is an optional dependency that you can opt out from.
3+
4+
To do so, install the [`@ember/optional-features`](https://github.com/emberjs/ember-optional-features) addon
5+
and disable the `jquery-integration` flag:
6+
7+
```shell
8+
ember install @ember/optional-features
9+
ember feature:disable jquery-integration
10+
```
11+
12+
This will remove jQuery from your `vendor.js` bundle and disable any use of jQuery in Ember itself.
13+
Now your app will be about 30KB lighter!
14+
15+
## Caveats
16+
17+
Without jQuery, any code that still relies on it will break, especially any usage of
18+
19+
* [`this.$()`](https://www.emberjs.com/api/ember/release/classes/Component/methods/$?anchor=%24) in components
20+
* `jQuery` or `$` directly as a global, through `Ember.$()` or by importing it (`import jQuery from jquery;`)
21+
* global acceptance test helpers like `find()` or `click()`
22+
* `this.$()` in component tests
23+
24+
Note that this also applies to all addons that your app uses, so make sure they support being used without jQuery.

0 commit comments

Comments
 (0)