27
loading...
Remodeling an Ember App - Codemods and jQuery
When you need to upgrade and ember app, codemods can help you update your app's syntax faster than you could make changes by hand. Today, we'll talk about codemods and cover what to do about jQuery usage in your apps.
This is Part 4 of a series of blog posts. We're on a journey together to remodel an older Ember app, ember-api-docs, incrementally bringing it up to date with the latest and best Ember and Ember Data patterns.
For this series, I'm pair programming with Chris Thoburn, aka @runspired, who is known for
his work on Ember Data. He has over 500 commits and some great
debugging skills that you and I can learn from.
his work on Ember Data. He has over 500 commits and some great
debugging skills that you and I can learn from.
So far, we have upgraded our dependencies and tests are all passing. This sets a strong foundation for running codemods and then making sure that tests keep passing.
Ember Octane is Ember's first "edition." You can think of an edition as a collection of features and syntax that together form a cohesive mental model. There are multiple ways to accomplish a feature in Ember, and Octaneified apps use the latest styles.
There is a CLI command that configures an app to use Octane:
npx @ember/octanify from which set some dependencies and flipped flags in optional-features.jsonYou can find more instructions about this command in the Ember upgrade guide. In short, it sets some dependencies in
package.json and feature flags in optional-features.json. Optional features are one way that new features are rolled out in Ember apps without making breaking changes. When you are ready, you can opt into them, but if you are not ready, you aren't blocked from upgrading. Regular upgrading is critical for companies and teams that value getting security, bugfixes, and feature updates over long periods of time.Octanify sets the following feature flags in
optional-features.json:{
"default-async-observers": true,
"jquery-integration": false,
"template-only-glimmer-components": true,
"application-template-wrapper": false,
}You can learn all about these individual features in the Optional Features Guide.
For our app, all the optional features set by Octanify were fine. Setting
jquery-integration: false meant that instead of using this.$() in our apps, we had to install @ember/jquery and import jQuery individually - no problem. However, the jquery-integration flag made us wonder, could we remove jQuery from our app altogether? We were only using it in one place in our app, and doing so would cut some kb from our app.However, we didn't just need to check our app. We also had to check if any addons used jQuery. I used to search my
node_modules for usages, but that would return a lot of false positives compared to a strategy that Chris Thoburn showed me.Chris first ran the build for the app:
npx ember buildBy default, the command puts built files in the
dist/ directory. Then, Chris was able to search for this.$ and Ember.$ and confirm that our app's addons did not need jQuery. This is better than searching node_modules, since we are only checking for the use of jQuery in addon features we are actually using.Another common use of jQuery in apps is via Ember Data. By default, Ember Data uses jQuery for its HTTP requests. However, if an app has
ember-fetch installed, it will use fetch instead. It's important to install ember-fetch in order to provide broad browser support for your fetch requests.Finally, we took another look at our direct use of jQuery in this app, in our Table of Contents component:
import { action } from '@ember/object';
import Component from '@ember/component';
import jQuery from 'jquery';
export default class TableOfContents extends Component {
@action
toggle(type) {
jQuery(this.element)
.find('ol.toc-level-1.' + type)
.slideToggle(200);
}
}jQuery is providing a nice open/close animation for one of our menus. Whenever I see jQuery in use, I always check youmightnotneedjquery to see if there's an easy alternative. In this case, there was not, so in the interest of moving forward, we leave jQuery in our app for now, and open an issue asking for help making a new CSS/plain JavaScript animation.
It's not a huge deal to leave jQuery in your app unless you have a strategic, benchmarked focus on app performance. jQuery is an incredibly successful project - so successful that its best features are now provided by native browser JavaScript. Ember's API documentation app is used by developers around the world with varying internet quality levels, and so we do need to save some kb where we can, however this one task should not block our progress towards improving other areas of the app.
Now on to some more codemods. Ember CLI Update can update your dependencies, and also provides a subset of the most common codemods that make deeper changes.
After running dependency updates, you can run the codemods like this:
# Start your app
npx ember serve
# Run the codemods
npx ember-cli-update --run-codemodsSome codemods start with the letters
fpe. This stands for "function prototype extension."There are many more codemods than those provided by Ember CLI update. One good place to look for them is ember-codemods on GitHub.
Some codemods require that you have your app running. That's why we start the app with
ember serve. Such codemods look at the built files in order to infer the correct changes to make. This is possible through a strategy called telemetry, via ember-codemods-telemetry-helpers.When we ran
ember-modules-codemod, we encountered an error. The codemod helpfully told us which line it failed on:titleToken(model) {
return model?.fn?.name;
}This line of code uses optional chaining, with
?. syntax. Optional chaining is a feature of JavaScript that was added after these codemods were initially written.We can see for ourselves one of the challenges of codemods - when they are written, they are a snapshot in time. It takes work to keep them functioning as JavaScript and Ember apps change. If you are working on a large app, it may be less work to fix a codemod bug than to make all the changes by hand. Additionally, codemods are written to work for individuals' apps, and so it takes community effort for codemods to work across many edge cases that authors could not forsee.
Another example of maintainability issues with codemods is the ES5 getter codemod - you have to run it before you run native classes codemods, because it doesn't know how to parse native classes. They didn't exist when the getter codemod was written. These aren't unsolvable problems, but they mean that developers whose apps are super out of date may have a harder time upgrading. There are many benefits to having a regular ugrade and maintenance schedule for your work, and this is one example.
Some of the codemods we ran introduced decorators. VSCode was our code editor of choice, and its default linters didn't like the use of decorators.
We removed
jsconfig.json from our app's .gitignore, and then configured VSCode to stop yelling about decorators in jsconfig.json:{
"compilerOptions": {
"experimentalDecorators": true
},
}Not all codemods are flawless. There's a lot of variation in an app! You should think of them has helpful suggestions, rather than a complete solution to your upgrade process. The best way to catch codemod mistakes is to carefully review the diff, run your tests, and make a commit after each codemod. Here's an example issue we had with a codemod that rewrote
link-to:// before codemod
// after codemod
<LinkTo @route= @models= @query=>The codemod cut out some of our route segments, leading to incorrect links in one part of the app:
// correct
/ember-data/3.26/classes/Ember.Inflector/methods/singular?anchor=singular
// incorrect
/ember-data/3.26/classes/ember-data/methods/3.26?anchor=singularHow did this happen? We took a look at the source code for the codemod, and saw that it has special handling for dynamic routes, query params, and data-test. When we used all three of these things together in one link-to, it was the perfect storm.
Our upgrade would have been easier if we ran a single codemod at a time, and make it its own commit, and ran it in CI, and shipped it. If you have the ability to roll your app back quickly in production, you don't need to work as carefully.
That said, you really need to go through the diff if you try to do a big bang upgrade.
If your test suite coverage is bad, and you can't improve it, you can run codemods on specific chunks of code and QA them - do one set of related components at a time, then look at the diff and click test. Many (or maybe all) codemods accept file paths in the CLI commands.
That's it for codemods! Next up, we will take a look at the code that couldn't be modded, and do some refactors to simplify the app now that we have Octane's awesome features available, such as
tracked. Thanks for reading!