Skip to content

Commit 5b5d1d0

Browse files
rwjbluerwjblue
authored
Merge pull request #294 from simonihmig/jquery-optional
Make jQuery optional
2 parents 78211b1 + 7523af7 commit 5b5d1d0

File tree

1 file changed

+280
-0
lines changed

1 file changed

+280
-0
lines changed

‎text/0000-optional-jquery.md

+280
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
- Start Date: 2018-01-11
2+
- RFC PR: github.com/emberjs/rfcs/pull/294
3+
- Ember Issue: (leave this empty)
4+
5+
# Make jQuery optional
6+
7+
## Summary
8+
9+
For the past Ember has been relying and depending on jQuery. This RFC proposes making jQuery optional and having a well
10+
defined way for users to opt-out of bundling jQuery.
11+
12+
## Motivation
13+
14+
### Why we don't need jQuery any more
15+
16+
One of the early goals of jQuery was cross-browser normalization, at a time where browser support for web standards was
17+
incomplete and inconsistent, and Internet Explorer 6 was the dominating browser. It provided a useful and convenient
18+
API for DOM traversal and manipulation as well as event handling, that hid the various browser differences and bugs from
19+
the user. For example `document.querySelector` wasn't a thing at that time, and browsers were using very different event
20+
models ([DOM Level 0, DOM Level 2 and IE's own proprietary model](https://en.wikipedia.org/wiki/DOM_events#Event_handling_models)).
21+
22+
But this level of browser normalization is not required anymore, as today's browsers all support the basic DOM APIs well
23+
enough. Even more so that the upcoming Ember 3.0 will drop support for all versions of Internet Explorer except 11.
24+
25+
Furthermore Ember users will need to directly traverse and modify the DOM or manually attach event listeners in very
26+
special cases only. Most of these low level interactions are taken care of by Ember's templates and its underlying
27+
Glimmer rendering engine, as well as action helpers or the component's event handler methods.
28+
29+
So having jQuery included by default does not provide that much value to users most of the time, and Ember itself is
30+
expected to be fully functional and tested without jQuery, presumably for the upcoming 3.0 stable release.
31+
32+
### What are the drawbacks of bundling jQuery
33+
34+
The major drawback is the increased bundle size, which amounts to [~29KB](https://mathiasbynens.be/demo/jquery-size)
35+
(minified and gzipped). This not only increases the loading time, but also parse and compile times, thus increasing the
36+
total time to interactive. This is especially true for mobile devices, where slow connectivity and weak CPU performance
37+
is not uncommon.
38+
39+
Having jQuery not included will improve the suitability of Ember for mobile applications considerably. Even
40+
if the raw number is not that huge, it all adds up. And it plays together with other efforts to make leaner Ember builds
41+
possible, like enabling tree shaking with the new [Module API](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md),
42+
moving code from core to addons (e.g. the [`Ember.String` deprecation](https://github.com/emberjs/rfcs/blob/master/text/0236-deprecation-ember-string.md))
43+
or the ["Explode RFC"](https://github.com/emberjs/rfcs/blob/explode/text/0000-explode.md). In that regard removing the
44+
dependency on jQuery is a rather low hanging fruit with an high impact.
45+
46+
### But this is already possible, why this RFC?
47+
48+
There is indeed a somewhat quirky way to build an [app without jQuery](https://github.com/rwjblue/no-jquery-app) even
49+
today.
50+
Although this *happens* to work, it is not sufficient to consider this officially supported for these reasons:
51+
* Ember itself must be fully tested to work without jQuery
52+
* the public APIs that depend on and/or expose jQuery need to have some well defined behavior when jQuery is not
53+
available
54+
* there should be a way to technically opt-out (other than fiddling with [`vendorFiles`](https://github.com/rwjblue/no-jquery-app/commit/34c40fc2cfc5e2ce0c39e5e906448c46af699d26))
55+
that is easier to use, understand and maintain
56+
* addons should mostly default to not use jQuery, to make removing jQuery practically possible for their consuming
57+
apps
58+
59+
## Detailed design
60+
61+
### Remove internal jQuery usage
62+
63+
As of writing this, there are [major efforts](https://github.com/emberjs/ember.js/issues/16058) underway to remove and
64+
cleanup the Ember codebase and especially its tests from jQuery usage. Having a way to fully test Ember without jQuery
65+
is a prerequisite to officially support jQuery being optional. When this is done, it will enable a "no jQuery" mode,
66+
that will make it not use jQuery anymore, but only native DOM APIs.
67+
68+
### Add an opt-out flag
69+
70+
There should be a global flag that will toggle the optional jQuery integration (true by default). When this is disabled,
71+
it will make Ember CLI's build process *not* include jQuery into the `vendor.js` bundle, *and* it will explicitly put
72+
Ember itself into its "no jQuery" mode.
73+
74+
The flag itself will not be made a public API. Rather it will be handled by a privileged addon, that will allow to
75+
disable the integration flag, thus to opt out from jQuery integration. This approach is in line with
76+
[RFC 278](https://github.com/emberjs/rfcs/pull/278) and [RFC 280](https://github.com/emberjs/rfcs/pull/280), to allow
77+
for some better implementation flexibility.
78+
79+
### Introduce `@ember/jquery` package
80+
81+
Currently Ember CLI itself is importing jQuery into the app's `vendor.js` file. To decouple it from this task, and
82+
to allow for some better flexibility in the future, the responsibility for importing jQuery is moved to a dedicated
83+
`@ember/jquery` addon.
84+
85+
To not create any breaking changes, Ember CLI will have to check the app's dependencies for the presence of this addon.
86+
If it is not present, it will continue importing jQuery *unless* the jQuery integration flag is disabled.
87+
If it is present, it will stop importing jQuery at all, and delegate this responsibility to the addon.
88+
89+
To nudge users to install `@ember/jquery` when they need jQuery, some warning/deprecation messages should be issued when
90+
the addon is *not* installed and the integration flag is either not specified or is set to true. To ease
91+
migration the addon should be placed in the default blueprint (until an eventual more aggressive deprecation of
92+
jQuery). Only in the case the app is actively opting out of jQuery integration the addon is not needed.
93+
94+
The addon itself has to make sure the Ember CLI version in use is at least the one that introduced the above mentioned
95+
logic, to prevent importing jQuery twice.
96+
97+
### Assertions for jQuery based APIs
98+
99+
Apart from testing (see below), Ember features some APIs that directly expose jQuery, which naturally cannot continue
100+
to work without it. For these APIs some assertions have to be added when running in "no jQuery" mode (and not in
101+
production), that provide some useful error messages for the developer:
102+
103+
* `Ember.$()`
104+
should throw an assertion stating that jQuery is not available.
105+
* `this.$()` in components
106+
should throw an assertion stating that jQuery is not available and that `this.element` and native DOM APIs should be
107+
used instead.
108+
109+
### Introducing `ember-jquery-legacy` and deprecating `jQuery.Event` usage
110+
111+
Event handler methods in components will usually receive an instance of [`jquery.Event`](http://api.jquery.com/category/events/event-object/) as an argument, which is very
112+
similar to native event objects, but not exactly the same. To name a few differences, not all properties of the native
113+
event are mapped to the jQuery event, on the other hand a jquery event has a `originalEvent` property referencing the
114+
native event.
115+
116+
The updated event dispatcher in Ember 3.0 is capable of working without jQuery (similar to what
117+
`ember-native-dom-event-dispatcher` provided for Ember 2.x). When jQuery is not available, it will naturally not be
118+
able to pass a `jquery.Event` instance but a native event instead. This creates some ambiguity for addons, as they
119+
cannot know in advance how the consuming app is built (with or without jQuery).
120+
121+
For code that does not rely on any `jQuery.Event` specific API, there is no need to change anything as it will continue
122+
to work with native DOM events.
123+
124+
But there are cases where jQuery specific properties have to be used (when jQuery events are passed). This is especially
125+
true for the `originalEvent` property, for example to access `TouchEvent` properties that are not exposed on the
126+
`jQuery.Event` instance itself. So there has to be a way to make the code work with either jQuery events or native
127+
events being passed to the event handler (especially important for addons). Moreover this should be done in a way that
128+
uses native DOM APIs only, to support the migration away from jQuery coupled code.
129+
130+
To solve this issue another addon `ember-jquery-legacy` will be introduced, which for now will only expose a single
131+
`normalizeEvent` function. This function will accept a native event as well as a jQuery event (possibly distinguishing
132+
between those two modes at build time, based on the jQuery integration flag), but will always return a native event
133+
only.
134+
135+
This will allow addon authors to work with both event types, but start to only use native DOM APIs:
136+
137+
```js
138+
import Component from '@ember/component';
139+
import { normalizeEvent } from 'ember-jquery-legacy';
140+
141+
export default Component.extend({
142+
click(event) {
143+
let nativeEvent = normalizeEvent(event);
144+
// from here on use only native DOM APIs...
145+
}
146+
})
147+
```
148+
149+
To encourage addon authors to refactor their jQuery coupled event code, the use of `jQuery.Event` specific APIs used for
150+
jQuery events passed to component event handlers should be deprecated and a deprecation message be shown when accessing
151+
them (e.g. `event.originalEvent`). Care must be taken though that this warning will not be issued when `normalizeEvent`
152+
has to access `originalEvent`.
153+
154+
Also for apps that do not want to transition away from jQuery and would be overloaded with unnecessary warnings, the
155+
deprecations should be silenced when the jQuery integration flag is explicitly set to true (and not just true by
156+
default). By doing so users effectively state their desire to continue using jQuery, thus any needless churn should
157+
be avoided for them.
158+
159+
### Testing
160+
161+
Ember's test harness has been based on jQuery for a long time. Most global acceptance test helpers like `find` or
162+
`click` rely on jQuery. For integration tests the direct use of jQuery like `this.$('button').click()` to trigger
163+
events or assert the state of the DOM is still the standard, based on `this.$()` returning a jQuery object representing
164+
the rendered result of the tests `render` call.
165+
166+
To be able to reliably run tests in a jQuery-less world, we need to run our tests without jQuery being included,
167+
so our test harness has to work without jQuery as well.
168+
169+
Fortunately this is well underway already. [ember-native-dom-helpers](https://github.com/cibernox/ember-native-dom-helpers)
170+
introduced native DOM test helpers for integration and acceptance tests as an user space addon. The recent acceptance
171+
testing [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md) provides
172+
similar test helpers, implemented in the `@ember/test-helpers` package, and envisages deprecating the global test
173+
helpers.
174+
175+
However while the existing jQuery based APIs are still available, when these are used without jQuery they have to throw
176+
an assertion with some meaningful error message:
177+
178+
* global acceptance test helpers that expect jQuery selectors (which are a potentially incompatible superset of standard
179+
CSS selectors)
180+
181+
* `this.$()` in component tests, provided currently by `@ember/test-helpers` in `moduleForComponent` and
182+
`setupRenderingTest`
183+
184+
In both cases the error message should state that jQuery is not available and that the native DOM based test helpers
185+
of the `@ember/test-helpers` package should be used instead.
186+
187+
The transitioning to these new test helpers can be eased through a codemod. For `ember-native-dom-helpers` there already
188+
exists [ember-native-dom-helpers-codemod](https://github.com/simonihmig/ember-native-dom-helpers-codemod), which
189+
could be adapted to the very similar RFC 268 based interaction helpers in `@ember/test-helpers`.
190+
191+
### Implementation outline
192+
193+
The following outlines how a possible implementation of the jQuery integration flag *could* look like. This
194+
is just to provide some additional context, but is *intentionally not* meant to be normative, to allow some flexibility
195+
for the actual implementation.
196+
197+
The addon that will handle the flag is expected to be [ember-optional-features](https://github.com/emberjs/ember-optional-features),
198+
which will read from and write to a `config/optional-features.{js,json}` file. This will hold the `jquery-integration`
199+
flag (amongst others). This flag in turn will be added to the `EmberENV` hash, which will make Ember go into its
200+
"no jQuery" mode when set to `false`.
201+
202+
Ember CLI and the `@ember/jquery` addon will also look for `jquery-integration` in this configuration file, and will
203+
opt-out of importing jQuery when this file is present and the flag is set to `false`.
204+
205+
## How we teach this
206+
207+
### Guides
208+
209+
The existing "Managing Dependencies" chapters in the Ember Guides as well as on ember-cli.com provide a good place to
210+
explain users how to set the jQuery integration flag by means of the mentioned [privileged addon](#add-an-opt-out-flag)
211+
that handles this flag.
212+
213+
The section on components should be updated to remove any eventually remaining references to `this.$`, to not let users
214+
fall into the trap of creating an implicit dependency on jQuery by "accidental" use of it. These should be changed to
215+
refer to their native DOM counterparts like `this.element` or `this.element.querySelector()`.
216+
217+
The section on acceptance tests will have been updated as per [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md)
218+
to use the new `@ember/test-helpers` based test helpers instead of the jQuery based global helpers.
219+
220+
The section on component tests should not use `this.$()` anymore as well, and instead also according to [RFC 268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md)
221+
use `this.element` to refer to the component's root element, and use the new DOM interaction helpers instead of jQuery
222+
events triggered through `this.$()`.
223+
224+
### Deprecation guide
225+
226+
The deprecation warnings introduced for using `jQuery.Event` specific APIs should explain the use of the
227+
`normalizeEvent` helper function to migrate towards native DOM APIs on the one side, and on the other side the effect of
228+
setting the jQuery integration flag to explicitly opt into jQuery usage thus suppressing the warnings.
229+
230+
### Addon migration
231+
232+
One of the biggest problems to easily opt-out of jQuery is that many addons still depend on it. Many of these usages
233+
seem to be rather "accidental", in that the full power of jQuery is not really needed for the given task, and could
234+
be fairly easily refactored to use only native DOM APIs.
235+
236+
For this reason this RFC encourages addon authors to not use jQuery anymore and to refactor existing usages whenever
237+
possible! This certainly does not apply categorically to all addons, e.g. those that wrap jQuery plugins as
238+
components and as such cannot drop this dependency.
239+
240+
#### ember-try
241+
242+
`ember-try`, which is used to test addons in different scenarios with different dependencies, should provide some means
243+
to define scenarios without jQuery, based on the jQuery integration flag introduced in this RFC.
244+
245+
Furthermore the Ember CLI blueprint for addons should be extended to include no-jQuery scenarios by default, to make
246+
sure addons don't cause errors when jQuery is not present.
247+
248+
#### emberobserver.com
249+
250+
It would be very helpful to have a clear indication on [emberobserver.com](https://emberobserver.com/) which
251+
addons depend on jQuery and which not. This would benefit users as to know which addons they can use without
252+
jQuery, but also serve as an incentive for authors to make their addons work without it.
253+
254+
Given the jQuery integration flag introduced in this RFC, this paves the way to automatically detect addons that are
255+
basically declaring their independence from jQuery by having this flag set to `false` (in their own repository).
256+
257+
## Drawbacks
258+
259+
### Churn
260+
261+
A vast amount of addons still depend on jQuery. While as far as this RFC is concerned no jQuery based APIs will be
262+
deprecated and the default will still be to include jQuery, addons are nevertheless encouraged to remove their
263+
dependency on jQuery, which will add some considerable churn to the addon ecosystem. As of writing this, there are:
264+
* [475 addons](https://emberobserver.com/code-search?codeQuery=Ember.%24) using `Ember.$`
265+
* [479 addons](https://emberobserver.com/code-search?codeQuery=this.%24&fileFilter=addon%2Fcomponents) using `this.$` in
266+
components
267+
* [994 addons](https://emberobserver.com/code-search?codeQuery=this.%24&fileFilter=tests) using `this.$` in tests
268+
269+
Among these are still some very essential addons like `ember-data`, which still relies on `$.ajax`, see
270+
[#5320](https://github.com/emberjs/data/issues/5320).
271+
272+
A good amount of that churn can be mitigated by having a codemod that migrates tests (see "Testing" above).
273+
274+
## Alternatives
275+
276+
Continue to depend on jQuery.
277+
278+
## Unresolved questions
279+
280+
None so far.

0 commit comments

Comments
 (0)